moxml 0.1.14 → 0.1.16

data/spec/moxml/lazy_parse_spec.rb

@@ -0,0 +1,115 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "support/allocation_helper"
+
+# Lazy parse correctness tests — these run in CI by default.
+# Verifies that lazy parse produces correct document structure
+# across all adapters without eager wrapper construction.
+RSpec.describe "Moxml lazy parse" do
+  let(:xml) do
+    "<root><child><nested>text</nested></child><sibling>more</sibling></root>"
+  end
+
+  shared_examples "lazy parse behavior" do |adapter_name|
+    let(:ctx) { Moxml::Context.new(adapter_name) }
+
+    describe "#parse" do
+      it "returns a Document without eagerly building wrapper tree" do
+        doc = ctx.parse(xml)
+        expect(doc).to be_a(Moxml::Document)
+        expect(doc.root).to be_a(Moxml::Element)
+        expect(doc.root.name).to eq("root")
+      end
+
+      it "provides correct children via lazy access" do
+        doc = ctx.parse(xml)
+        root = doc.root
+        children = root.children.to_a
+        expect(children.size).to eq(2)
+        expect(children[0]).to be_a(Moxml::Element)
+        expect(children[0].name).to eq("child")
+        expect(children[1].name).to eq("sibling")
+      end
+
+      it "provides correct nested children" do
+        doc = ctx.parse(xml)
+        nested = doc.root.children[0].children[0]
+        expect(nested.name).to eq("nested")
+        expect(nested.text).to eq("text")
+      end
+
+      it "preserves attributes" do
+        xml_with_attrs = '<root a="1" b="2"><child c="3"/></root>'
+        doc = ctx.parse(xml_with_attrs)
+        root = doc.root
+        attrs = root.attributes
+        expect(attrs.size).to eq(2)
+        expect(root["a"]).to eq("1")
+        expect(root["b"]).to eq("2")
+        expect(root.children[0]["c"]).to eq("3")
+      end
+
+      it "preserves text content" do
+        doc = ctx.parse("<root>hello world</root>")
+        expect(doc.root.text).to eq("hello world")
+      end
+
+      it "preserves mixed content" do
+        mixed_xml = "<root>before<child/>after</root>"
+        doc = ctx.parse(mixed_xml)
+        expect(doc.root.text).to eq("beforeafter")
+      end
+
+      it "handles comments" do
+        comment_xml = "<root><!-- a comment --><child/></root>"
+        doc = ctx.parse(comment_xml)
+        children = doc.root.children.to_a
+        comment = children.find(&:comment?)
+        expect(comment).not_to be_nil
+        expect(comment.content).to include("a comment")
+      end
+
+      it "handles processing instructions" do
+        pi_xml = "<?pi-target pi-content?><root/>"
+        doc = ctx.parse(pi_xml)
+        expect(doc.root.name).to eq("root")
+      end
+
+      it "handles namespace declarations" do
+        ns_xml = '<root xmlns:ns="http://example.com"><ns:child/></root>'
+        doc = ctx.parse(ns_xml)
+        root = doc.root
+        nss = root.namespaces
+        expect(nss.size).to be >= 1
+      end
+
+      it "round-trips through serialize" do
+        doc = ctx.parse(xml)
+        serialized = doc.to_xml
+        doc2 = ctx.parse(serialized)
+        expect(doc2.root.name).to eq("root")
+        expect(doc2.root.children.to_a.size).to eq(2)
+      end
+    end
+  end
+
+  # Run for all guarded adapters
+  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 "lazy parse behavior", adapter_name
+
+      # CDATA behavior differs between adapters
+      it "handles CDATA sections" do
+        ctx = Moxml::Context.new(adapter_name)
+        cdata_xml = "<root><![CDATA[<not xml>]]></root>"
+        doc = ctx.parse(cdata_xml)
+        expect(doc.root).not_to be_nil
+      end
+    end
+  end
+end

data/spec/moxml/namespace_uri_validation_spec.rb

@@ -92,10 +92,10 @@ RSpec.describe "Namespace URI validation" do
     end
   end
 
-  describe "lenient namespace_uri_mode" do
+  describe "lenient namespace_validation_mode" do
     let(:context) do
       Moxml.new do |config|
-        config.namespace_uri_mode = :lenient
+        config.namespace_validation_mode = :lenient
       end
     end
 
@@ -134,7 +134,15 @@ RSpec.describe "Namespace URI validation" do
     end
 
     it "still accepts valid URIs" do
-      expect { element.add_namespace("ns", "http://example.com") }.not_to raise_error
+      expect do
+        element.add_namespace("ns", "http://example.com")
+      end.not_to raise_error
+    end
+
+    it "accepts prefixes with dots in lenient mode" do
+      expect do
+        element.add_namespace("xmlns_1.0", "http://example.com")
+      end.not_to raise_error
     end
   end
 end

data/spec/moxml/node_cache_spec.rb

@@ -0,0 +1,110 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "support/allocation_helper"
+
+# Node caching correctness tests — these run in CI by default.
+# Verifies that cache semantics (identity, invalidation) work correctly
+# across all adapters.
+RSpec.describe "Moxml node caching" do
+  shared_examples "cached children" do |adapter_name|
+    let(:ctx) { Moxml::Context.new(adapter_name) }
+    let(:xml) { "<root><a/><b/><c/></root>" }
+    let(:doc) { ctx.parse(xml) }
+    let(:root) { doc.root }
+
+    describe "Node#children caching" do
+      it "returns the same NodeSet object on repeated calls" do
+        children1 = root.children
+        children2 = root.children
+        expect(children1).to equal(children2)
+      end
+
+      it "returns consistent child elements across calls" do
+        children1 = root.children.to_a
+        children2 = root.children.to_a
+        expect(children1.map(&:name)).to eq(children2.map(&:name))
+      end
+
+      it "invalidates cache when a child is added" do
+        children_before = root.children
+        root.add_child(ctx.parse("<d/>").root)
+        children_after = root.children
+        expect(children_before).not_to equal(children_after)
+        expect(children_after.to_a.size).to eq(4)
+      end
+
+      it "invalidates cache when text is set" do
+        children_before = root.children
+        root.text = "new text"
+        children_after = root.children
+        expect(children_before).not_to equal(children_after)
+      end
+    end
+
+    describe "Element#attributes caching" do
+      let(:attr_xml) { '<root a="1" b="2"><child c="3"/></root>' }
+      let(:attr_doc) { ctx.parse(attr_xml) }
+      let(:attr_root) { attr_doc.root }
+
+      it "returns the same array on repeated calls" do
+        attrs1 = attr_root.attributes
+        attrs2 = attr_root.attributes
+        expect(attrs1).to equal(attrs2)
+      end
+
+      it "returns consistent attribute values" do
+        attrs = attr_root.attributes
+        expect(attrs.to_h do |a|
+          [a.name, a.value]
+        end).to eq({ "a" => "1", "b" => "2" })
+      end
+
+      it "invalidates cache when an attribute is set" do
+        attrs_before = attr_root.attributes
+        attr_root["c"] = "3"
+        attrs_after = attr_root.attributes
+        expect(attrs_before).not_to equal(attrs_after)
+        expect(attrs_after.size).to eq(3)
+      end
+
+      it "invalidates cache when an attribute is removed" do
+        attrs_before = attr_root.attributes
+        attr_root.remove_attribute("a")
+        attrs_after = attr_root.attributes
+        expect(attrs_before).not_to equal(attrs_after)
+        expect(attrs_after.size).to eq(1)
+      end
+    end
+
+    describe "Element#namespaces caching" do
+      let(:ns_xml) { '<root xmlns:a="http://a.com" xmlns:b="http://b.com"><a:child/></root>' }
+      let(:ns_doc) { ctx.parse(ns_xml) }
+      let(:ns_root) { ns_doc.root }
+
+      it "returns the same array on repeated calls" do
+        nss1 = ns_root.namespaces
+        nss2 = ns_root.namespaces
+        expect(nss1).to equal(nss2)
+      end
+
+      it "invalidates cache when a namespace is added" do
+        nss_before = ns_root.namespaces
+        ns_root.add_namespace("c", "http://c.com")
+        nss_after = ns_root.namespaces
+        expect(nss_before).not_to equal(nss_after)
+        expect(nss_after.size).to eq(3)
+      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 children", adapter_name
+    end
+  end
+end

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/moxml/xpath/axes_spec.rb

@@ -222,7 +222,7 @@ RSpec.describe "XPath Axes" do
     end
 
     it "combines attribute axis with wildcards" do
-      skip "HeadedOx limitation: Attribute wildcard (@*) not supported by XPath parser. See docs/HEADED_OX_LIMITATIONS.md"
+      skip "HeadedOx limitation: Attribute wildcard (@*) not supported by XPath parser. See docs/_pages/headed-ox-limitations.adoc"
       ast = Moxml::XPath::Parser.parse("//book/@*")
       proc = Moxml::XPath::Compiler.compile_with_cache(ast)
       result = proc.call(book_doc)

data/spec/moxml/xpath/compiler_spec.rb

@@ -153,7 +153,7 @@ RSpec.describe Moxml::XPath::Compiler do
     end
 
     it "works with wildcards" do
-      skip "HeadedOx limitation: Wildcard count differs due to Ox's DOM structure. See docs/HEADED_OX_LIMITATIONS.md"
+      skip "HeadedOx limitation: Wildcard count differs due to Ox's DOM structure. See docs/_pages/headed-ox-limitations.adoc"
       ast = Moxml::XPath::Parser.parse("//*")
       proc = described_class.compile_with_cache(ast)
       result = proc.call(nested_doc)
@@ -189,7 +189,7 @@ RSpec.describe Moxml::XPath::Compiler do
     end
 
     it "works with wildcards" do
-      skip "HeadedOx limitation: Attribute wildcard (@*) not supported by XPath parser. See docs/HEADED_OX_LIMITATIONS.md"
+      skip "HeadedOx limitation: Attribute wildcard (@*) not supported by XPath parser. See docs/_pages/headed-ox-limitations.adoc"
       ast = Moxml::XPath::Parser.parse("/root/book/@*")
       proc = described_class.compile_with_cache(ast)
       result = proc.call(attr_doc)

data/spec/moxml/xpath/functions/position_functions_spec.rb

@@ -30,7 +30,7 @@ RSpec.describe "XPath Position Functions" do
 
     # These tests require predicate support to be implemented
     # They are marked as pending until predicates are working
-    xit "returns current position in predicate" do
+    it "returns current position in predicate" do
       ast = Moxml::XPath::Parser.parse("/root/item[position() = 2]")
       proc = Moxml::XPath::Compiler.compile_with_cache(ast)
       result = proc.call(doc)
@@ -39,7 +39,7 @@ RSpec.describe "XPath Position Functions" do
       expect(result.first.text).to eq("second")
     end
 
-    xit "works with position comparison" do
+    it "works with position comparison" do
       ast = Moxml::XPath::Parser.parse("/root/item[position() > 1]")
       proc = Moxml::XPath::Compiler.compile_with_cache(ast)
       result = proc.call(doc)
@@ -63,7 +63,7 @@ RSpec.describe "XPath Position Functions" do
 
     # These tests require predicate support to be implemented
     # They are marked as pending until predicates are working
-    xit "returns size of context in predicate" do
+    it "returns size of context in predicate" do
       ast = Moxml::XPath::Parser.parse("/root/item[position() = last()]")
       proc = Moxml::XPath::Compiler.compile_with_cache(ast)
       result = proc.call(doc)
@@ -72,7 +72,7 @@ RSpec.describe "XPath Position Functions" do
       expect(result.first.text).to eq("third")
     end
 
-    xit "works with last() - 1" do
+    it "works with last() - 1" do
       ast = Moxml::XPath::Parser.parse("/root/item[position() = last() - 1]")
       proc = Moxml::XPath::Compiler.compile_with_cache(ast)
       result = proc.call(doc)
@@ -81,7 +81,7 @@ RSpec.describe "XPath Position Functions" do
       expect(result.first.text).to eq("second")
     end
 
-    xit "works with comparison to last()" do
+    it "works with comparison to last()" do
       ast = Moxml::XPath::Parser.parse("/root/item[position() < last()]")
       proc = Moxml::XPath::Compiler.compile_with_cache(ast)
       result = proc.call(doc)

data/spec/moxml/xpath/functions/special_functions_spec.rb

@@ -66,7 +66,7 @@ RSpec.describe "XPath Special Functions" do
     end
 
     # Test with nodeset argument - requires path evaluation
-    xit "accepts nodeset argument containing IDs" do
+    it "accepts nodeset argument containing IDs" do
       xml = <<~XML
         <root>
           <item id="a">first</item>

data/spec/performance/memory_usage_spec.rb

@@ -51,10 +51,6 @@ RSpec.shared_examples "Memory Usage Examples" do
     end
 
     it "handles streaming processing" do
-      if context.config.adapter_name == :headed_ox
-        pending "HeadedOx double-wrapping issue with file-based parsing"
-      end
-
       # Process file
       doc = nil
       File.open("spec/fixtures/small.xml") do |f|

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