moxml 0.1.14 → 0.1.16

data/spec/integration/shared_examples/node_wrappers/entity_reference_behavior.rb

@@ -0,0 +1,224 @@
+# frozen_string_literal: true
+
+RSpec.shared_examples "Moxml::EntityReference" do
+  let(:context) { Moxml.new }
+
+  describe "entity reference node" do
+    let(:doc) { context.create_document }
+
+    before do
+      root = doc.create_element("root")
+      doc.add_child(root)
+    end
+
+    describe "creation" do
+      it "creates an entity reference node" do
+        ref = doc.create_entity_reference("nbsp")
+        expect(ref).to be_a(Moxml::EntityReference)
+      end
+
+      it "has empty text content" do
+        ref = doc.create_entity_reference("amp")
+        expect(ref.text).to eq("")
+        expect(ref.content).to eq("")
+      end
+
+      it "exposes entity name" do
+        ref = doc.create_entity_reference("mdash")
+        expect(ref.name).to eq("mdash")
+      end
+
+      it "is recognized as entity_reference type" do
+        ref = doc.create_entity_reference("copy")
+        expect(ref.entity_reference?).to be true
+        expect(ref).not_to be_element
+        expect(ref).not_to be_text
+      end
+
+      it "validates entity reference name" do
+        expect { doc.create_entity_reference("123invalid") }.to raise_error(Moxml::ValidationError)
+      end
+    end
+
+    describe "serialization" do
+      it "serializes to entity syntax" do
+        ref = doc.create_entity_reference("nbsp")
+        expect(ref.to_xml).to eq(" ")
+      end
+
+      it "serializes standard XML entities" do
+        ref = doc.create_entity_reference("amp")
+        expect(ref.to_xml).to eq("&")
+      end
+    end
+
+    describe "tree integration" do
+      it "survives add_child and retrieval" do
+        root = doc.root
+        ref = doc.create_entity_reference("nbsp")
+        root.add_child(ref)
+        children = root.children
+        expect(children.size).to be >= 1
+        first = children.last
+        expect(first).to be_a(Moxml::EntityReference)
+        expect(first.name).to eq("nbsp")
+      end
+
+      it "serializes within element content" do
+        root = doc.root
+        root.add_child(doc.create_text("before"))
+        root.add_child(doc.create_entity_reference("nbsp"))
+        root.add_child(doc.create_text("after"))
+        xml = doc.to_xml
+        expect(xml).to include(" ")
+        expect(xml).to include("before")
+        expect(xml).to include("after")
+      end
+
+      it "supports multiple entity references" do
+        root = doc.root
+        root.add_child(doc.create_entity_reference("nbsp"))
+        root.add_child(doc.create_entity_reference("copy"))
+        root.add_child(doc.create_entity_reference("mdash"))
+        xml = doc.to_xml
+        expect(xml).to include(" ")
+        expect(xml).to include("©")
+        expect(xml).to include("—")
+      end
+    end
+
+    describe "equality" do
+      it "has the same name as another entity reference with same name" do
+        ref1 = doc.create_entity_reference("amp")
+        ref2 = doc.create_entity_reference("amp")
+        expect(ref1.name).to eq(ref2.name)
+      end
+
+      it "does not equal entity reference with different name" do
+        ref1 = doc.create_entity_reference("amp")
+        ref2 = doc.create_entity_reference("nbsp")
+        expect(ref1.name).not_to eq(ref2.name)
+      end
+    end
+  end
+
+  describe "entity reference via builder DSL" do
+    it "creates entity references" do
+      built = Moxml::Builder.new(context).build do
+        element("p") { entity_reference("nbsp") }
+      end
+      expect(built.root.children.last).to be_a(Moxml::EntityReference)
+      expect(built.root.children.last.name).to eq("nbsp")
+      expect(built.to_xml).to include(" ")
+    end
+
+    it "mixes text and entity references" do
+      built = Moxml::Builder.new(context).build do
+        element("p") do
+          text "Copyright"
+          entity_reference("copy")
+          text " 2024"
+        end
+      end
+      xml = built.to_xml
+      expect(xml).to include("Copyright")
+      expect(xml).to include("©")
+      expect(xml).to include("2024")
+    end
+  end
+
+  describe "entity restoration" do
+    it "restores standard XML entities when enabled" do
+      ctx_restore = Moxml.new(context.config.adapter_name) { |c| c.restore_entities = true }
+      doc = ctx_restore.parse("<p>a&amp;b</p>")
+      output = doc.to_xml
+      expect(output).to include("&amp;")
+    end
+
+    it "does not create entity references when disabled" do
+      ctx_no_restore = Moxml.new(context.config.adapter_name) { |c| c.restore_entities = false }
+      doc = ctx_no_restore.parse("<p>text</p>")
+      refs = doc.root.children.select { |c| c.is_a?(Moxml::EntityReference) }
+      expect(refs).to be_empty
+    end
+  end
+
+  describe "EntityRegistry#should_restore?" do
+    let(:registry) { context.entity_registry }
+
+    let(:config_on) do
+      cfg = Moxml::Config.new(context.config.adapter_name)
+      cfg.restore_entities = true
+      cfg
+    end
+
+    let(:config_off) do
+      cfg = Moxml::Config.new(context.config.adapter_name)
+      cfg.restore_entities = false
+      cfg
+    end
+
+    it "always restores the 5 standard XML entities" do
+      expect(registry.should_restore?(0x26, config: config_on)).to be true   # amp
+      expect(registry.should_restore?(0x3C, config: config_on)).to be true   # lt
+      expect(registry.should_restore?(0x3E, config: config_on)).to be true   # gt
+      expect(registry.should_restore?(0x22, config: config_on)).to be true   # quot
+      expect(registry.should_restore?(0x27, config: config_on)).to be true   # apos
+    end
+
+    it "restores standard XML entities even when restore_entities is false" do
+      expect(registry.should_restore?(0x26, config: config_off)).to be true  # amp
+      expect(registry.should_restore?(0x3C, config: config_off)).to be true  # lt
+    end
+
+    it "restores non-standard entities only when restore_entities is true" do
+      expect(registry.should_restore?(0xA0, config: config_on)).to be true   # nbsp
+      expect(registry.should_restore?(0xA0, config: config_off)).to be false
+    end
+
+    it "does not restore unknown codepoints" do
+      expect(registry.should_restore?(0xDEAD, config: config_on)).to be false
+    end
+  end
+
+  describe "entity_restoration_mode" do
+    let(:registry) { context.entity_registry }
+
+    it "defaults to :lenient" do
+      cfg = Moxml::Config.new(context.config.adapter_name)
+      expect(cfg.entity_restoration_mode).to eq(:lenient)
+    end
+
+    it "accepts :strict" do
+      cfg = Moxml::Config.new(context.config.adapter_name)
+      cfg.entity_restoration_mode = :strict
+      expect(cfg.entity_restoration_mode).to eq(:strict)
+    end
+
+    it "rejects invalid modes" do
+      cfg = Moxml::Config.new(context.config.adapter_name)
+      expect { cfg.entity_restoration_mode = :bogus }.to raise_error(ArgumentError)
+    end
+
+    it "restores non-standard entities in lenient mode" do
+      cfg = Moxml::Config.new(context.config.adapter_name)
+      cfg.restore_entities = true
+      cfg.entity_restoration_mode = :lenient
+      expect(registry.should_restore?(0xA0, config: cfg)).to be true
+    end
+
+    it "restores non-standard entities in strict mode (until DTD parsing)" do
+      cfg = Moxml::Config.new(context.config.adapter_name)
+      cfg.restore_entities = true
+      cfg.entity_restoration_mode = :strict
+      expect(registry.should_restore?(0xA0, config: cfg)).to be true
+    end
+
+    it "does not restore non-standard entities when restore_entities is false" do
+      cfg = Moxml::Config.new(context.config.adapter_name)
+      cfg.restore_entities = false
+      cfg.entity_restoration_mode = :lenient
+      expect(registry.should_restore?(0xA0, config: cfg)).to be false
+    end
+  end
+end

data/spec/integration/shared_examples/node_wrappers/node_behavior.rb

@@ -110,7 +110,7 @@ RSpec.shared_examples "Moxml::Node" do
           pending "Ox doesn't have a native XPath"
         end
         if context.config.adapter_name == :headed_ox
-          skip "HeadedOx limitation: Text content access from nested elements needs investigation. See docs/HEADED_OX_LIMITATIONS.md"
+          skip "HeadedOx limitation: Text content access from nested elements needs investigation. See docs/_pages/headed-ox-limitations.adoc"
         end
 
         node = doc.at_xpath("//b")

data/spec/moxml/adapter/headed_ox_spec.rb

@@ -41,7 +41,7 @@ RSpec.describe Moxml::Adapter::HeadedOx do
     it "executes simple XPath queries" do
       result = adapter.xpath(doc, "/root/book")
 
-      expect(result).to be_a(Moxml::NodeSet)
+      expect(result).to be_a(Array)
       expect(result.size).to eq(3)
     end
 
@@ -71,19 +71,19 @@ RSpec.describe Moxml::Adapter::HeadedOx do
     end
 
     it "supports XPath string functions in predicates" do
-      skip "HeadedOx limitation: Text content access from nested elements needs investigation. See docs/HEADED_OX_LIMITATIONS.md"
       result = adapter.xpath(doc, "//book[contains(title, '2')]")
 
       expect(result.size).to eq(1)
-      expect(result.first.xpath("title").first.text).to eq("Book 2")
+      book = Moxml::Node.wrap(result.first, doc.context)
+      expect(book.xpath("title").first.text).to eq("Book 2")
     end
 
     it "supports XPath position functions" do
-      skip "HeadedOx limitation: Text content access from nested elements needs investigation. See docs/HEADED_OX_LIMITATIONS.md"
       result = adapter.xpath(doc, "//book[position() = 2]")
 
       expect(result.size).to eq(1)
-      expect(result.first.xpath("title").first.text).to eq("Book 2")
+      book = Moxml::Node.wrap(result.first, doc.context)
+      expect(book.xpath("title").first.text).to eq("Book 2")
     end
 
     it "supports descendant axis" do
@@ -145,7 +145,7 @@ RSpec.describe Moxml::Adapter::HeadedOx do
     it "returns first matching node" do
       result = adapter.at_xpath(doc, "//book")
 
-      expect(result).to be_a(Moxml::Element)
+      expect(result).to be_a(::Ox::Element)
       expect(result.name).to eq("book")
     end
 
@@ -301,10 +301,10 @@ RSpec.describe Moxml::Adapter::HeadedOx do
       end
 
       it "supports last()" do
-        skip "HeadedOx limitation: Text content access from nested elements needs investigation. See docs/HEADED_OX_LIMITATIONS.md"
         result = adapter.xpath(doc, "//book[position() = last()]")
         expect(result.size).to eq(1)
-        expect(result.first.xpath("title").first.text).to eq("Book 3")
+        book = Moxml::Node.wrap(result.first, doc.context)
+        expect(book.xpath("title").first.text).to eq("Book 3")
       end
     end
   end

data/spec/moxml/adapter/oga_spec.rb

@@ -119,4 +119,50 @@ RSpec.describe Moxml::Adapter::Oga do
       expect(serialized).not_to include("\x01")
     end
   end
+
+  describe "doctype handling" do
+    it "correctly parses PUBLIC doctype" do
+      xml = '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html/>'
+      doc = described_class.parse(xml)
+      doctype = doc.children.find { |c| c.is_a?(Moxml::Doctype) }
+
+      expect(doctype.name).to eq("html")
+      expect(doctype.external_id).to eq("-//W3C//DTD XHTML 1.0 Strict//EN")
+      expect(doctype.system_id).to eq("http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd")
+    end
+
+    it "correctly parses SYSTEM doctype" do
+      xml = '<!DOCTYPE config SYSTEM "config.dtd"><config/>'
+      doc = described_class.parse(xml)
+      doctype = doc.children.find { |c| c.is_a?(Moxml::Doctype) }
+
+      expect(doctype.name).to eq("config")
+      expect(doctype.external_id).to be_nil
+      expect(doctype.system_id).to eq("config.dtd")
+    end
+
+    it "correctly parses simple doctype" do
+      xml = "<!DOCTYPE html><html/>"
+      doc = described_class.parse(xml)
+      doctype = doc.children.find { |c| c.is_a?(Moxml::Doctype) }
+
+      expect(doctype.name).to eq("html")
+      expect(doctype.external_id).to be_nil
+      expect(doctype.system_id).to be_nil
+    end
+
+    it "round-trips PUBLIC doctype" do
+      xml = '<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html/>'
+      doc = described_class.parse(xml)
+
+      expect(doc.to_xml).to include('PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"')
+    end
+
+    it "round-trips SYSTEM doctype" do
+      xml = '<!DOCTYPE config SYSTEM "config.dtd"><config/>'
+      doc = described_class.parse(xml)
+
+      expect(doc.to_xml).to include('SYSTEM "config.dtd"')
+    end
+  end
 end

data/spec/moxml/adapter/shared_examples/adapter_contract.rb

@@ -4,18 +4,7 @@
 # A better way is to run it through Moxml wrappers
 RSpec.shared_examples "xml adapter" do
   let(:xml) do
-    <<~XML
-      <?xml version="1.0"?>
-      <root xmlns="http://example.org" xmlns:x="http://example.org/x">
-        <child id="1">Text</child>
-        <child id="2"/>
-        <x:special>
-          <![CDATA[Some <special> text]]>
-          <!-- A comment -->
-          <?pi target?>
-        </x:special>
-      </root>
-    XML
+    '<?xml version="1.0"?><root xmlns="http://example.org" xmlns:x="http://example.org/x"><child id="1">Text</child><child id="2"/><x:special><![CDATA[Some <special> text]]><!-- A comment --><?pi target?></x:special></root>'
   end
 
   describe ".parse" do

data/spec/moxml/allocation_benchmark_spec.rb

@@ -0,0 +1,96 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "support/allocation_helper"
+
+# Detailed allocation benchmarks — only run with RUN_PERFORMANCE=1.
+# These measure exact allocation counts and compare across adapters.
+RSpec.describe "Moxml allocation benchmarks", :performance do
+  shared_examples "reduced allocations" do |adapter_name|
+    let(:ctx) { Moxml::Context.new(adapter_name) }
+
+    it "parse allocates fewer objects than a 100-element baseline" do
+      xml = generate_xml(100)
+      allocs = AllocationHelper.count_allocations { ctx.parse(xml) }
+      # Before lazy parse: ~18,000 allocations for 100 elements via DocumentBuilder
+      # After lazy parse: should be dramatically less (document wrapper + root only)
+      expect(allocs).to be < 5000,
+                        "Expected <5000 allocations for 100-element parse, got #{allocs}"
+    end
+
+    it "parse + root access is allocation-efficient" do
+      xml = generate_xml(50)
+      allocs = AllocationHelper.count_allocations do
+        doc = ctx.parse(xml)
+        doc.root.name
+      end
+      expect(allocs).to be < 2000,
+                        "Expected <2000 allocations for parse + root.name, got #{allocs}"
+    end
+
+    it "children access is cached (repeated calls don't increase allocations)" do
+      xml = "<root><a/><b/><c/></root>"
+      doc = ctx.parse(xml)
+      root = doc.root
+
+      allocs1 = AllocationHelper.count_allocations { root.children.to_a }
+      allocs2 = AllocationHelper.count_allocations { root.children.to_a }
+
+      # Second call should allocate fewer objects because children are cached
+      expect(allocs2).to be <= allocs1,
+                         "Second children.to_a (#{allocs2}) should allocate <= first (#{allocs1})"
+    end
+
+    it "attributes access is cached" do
+      xml = '<root a="1" b="2" c="3"><child d="4"/></root>'
+      doc = ctx.parse(xml)
+      root = doc.root
+
+      allocs1 = AllocationHelper.count_allocations { root.attributes }
+      allocs2 = AllocationHelper.count_allocations { root.attributes }
+
+      expect(allocs2).to be <= allocs1,
+                         "Second attributes call (#{allocs2}) should allocate <= first (#{allocs1})"
+    end
+
+    it "namespaces access is cached" do
+      xml = '<root xmlns:a="http://a.com" xmlns:b="http://b.com"><a:child/></root>'
+      doc = ctx.parse(xml)
+      root = doc.root
+
+      allocs1 = AllocationHelper.count_allocations { root.namespaces }
+      allocs2 = AllocationHelper.count_allocations { root.namespaces }
+
+      expect(allocs2).to be <= allocs1,
+                         "Second namespaces call (#{allocs2}) should allocate <= first (#{allocs1})"
+    end
+
+    it "NodeSet iteration is cached (second iteration allocates less)" do
+      xml = generate_xml(20)
+      doc = ctx.parse(xml)
+      root = doc.root
+
+      allocs1 = AllocationHelper.count_allocations do
+        root.children.each do |_c|
+        end
+      end
+      allocs2 = AllocationHelper.count_allocations do
+        root.children.each do |_c|
+        end
+      end
+
+      expect(allocs2).to be <= allocs1,
+                         "Second NodeSet iteration (#{allocs2}) should allocate <= first (#{allocs1})"
+    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 "reduced allocations", adapter_name
+    end
+  end
+end