moxml 0.1.16 → 0.1.18

data/spec/moxml/entity_preservation_spec.rb

@@ -0,0 +1,130 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.describe "Entity preservation across adapters" do
+  shared_examples "consistent entity handling" do
+    describe "text content with entities" do
+      it "preserves single entity in inner_text" do
+        doc = adapter.parse("<root>&copy; 2024</root>")
+        expect(doc.root.inner_text).to eq("&copy; 2024")
+      end
+
+      it "preserves multiple entities in inner_text" do
+        doc = adapter.parse("<root>&copy; text &mdash; end</root>")
+        expect(doc.root.inner_text).to eq("&copy; text &mdash; end")
+      end
+
+      it "preserves entity at start" do
+        doc = adapter.parse("<root>&copy; start</root>")
+        expect(doc.root.inner_text).to include("&copy;")
+      end
+
+      it "preserves entity at end" do
+        doc = adapter.parse("<root>end &copy;</root>")
+        expect(doc.root.inner_text).to include("&copy;")
+      end
+
+      it "does not alter standard entities" do
+        doc = adapter.parse("<root>&amp; &lt; &gt;</root>")
+        expect(doc.root.inner_text).to eq("& < >")
+      end
+    end
+
+    describe "to_xml round-trip" do
+      it "preserves entity in serialized output" do
+        doc = adapter.parse("<root>&copy; 2024</root>")
+        expect(doc.root.to_xml(declaration: false)).to include("&copy;")
+      end
+
+      it "preserves multiple entities in serialized output" do
+        doc = adapter.parse("<root>&copy; text &mdash; end</root>")
+        xml = doc.root.to_xml(declaration: false)
+        expect(xml).to include("&copy;")
+        expect(xml).to include("&mdash;")
+      end
+
+      it "does not double-escape standard entities" do
+        doc = adapter.parse("<root>&amp; test</root>")
+        xml = doc.root.to_xml(declaration: false)
+        expect(xml).not_to include("&amp;amp;")
+      end
+    end
+
+    describe "attribute values with entities" do
+      it "preserves entity in attribute value" do
+        doc = adapter.parse('<root attr="&copy; 2024"/>')
+        expect(doc.root["attr"]).to eq("&copy; 2024")
+      end
+
+      it "preserves entity in attribute via Attribute#value" do
+        doc = adapter.parse('<root attr="&copy; 2024"/>')
+        attr = doc.root.attributes.first
+        expect(attr.value).to eq("&copy; 2024")
+      end
+
+      it "preserves entity in attribute to_xml" do
+        doc = adapter.parse('<root attr="&copy; 2024"/>')
+        xml = doc.root.to_xml(declaration: false)
+        expect(xml).to include('attr="&copy; 2024"')
+      end
+    end
+
+    describe "Text node content" do
+      it "preserves entity in Text#content" do
+        doc = adapter.parse("<root>&copy; text</root>")
+        text_nodes = doc.root.children.grep(Moxml::Text)
+        combined = text_nodes.map(&:content).join
+        expect(combined).to include("&copy;")
+      end
+    end
+  end
+
+  context "with nokogiri adapter" do
+    let(:adapter) { Moxml::Adapter::Nokogiri }
+
+    before { require "moxml/adapter/nokogiri" }
+
+    it_behaves_like "consistent entity handling"
+  end
+
+  context "with oga adapter" do
+    let(:adapter) { Moxml::Adapter::Oga }
+
+    before { require "moxml/adapter/oga" }
+
+    it_behaves_like "consistent entity handling"
+  end
+
+  context "with rexml adapter" do
+    let(:adapter) { Moxml::Adapter::Rexml }
+
+    before { require "moxml/adapter/rexml" }
+
+    it_behaves_like "consistent entity handling"
+  end
+
+  context "with ox adapter" do
+    let(:adapter) { Moxml::Adapter::Ox }
+
+    before { require "moxml/adapter/ox" }
+
+    it_behaves_like "consistent entity handling"
+  end
+
+  context "with headed_ox adapter" do
+    let(:adapter) { Moxml::Adapter::HeadedOx }
+
+    before { require "moxml/adapter/headed_ox" }
+
+    it_behaves_like "consistent entity handling"
+  end
+
+  context "with libxml adapter" do
+    let(:adapter) { Moxml::Adapter::Libxml }
+
+    before { require "moxml/adapter/libxml" }
+
+    it_behaves_like "consistent entity handling"
+  end
+end

data/spec/moxml/entity_reference_spec.rb

@@ -0,0 +1,114 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+RSpec.shared_examples "entity reference node" do |adapter_name|
+  context "with #{adapter_name} adapter", adapter: adapter_name do
+    let(:ctx) { Moxml.new(adapter_name) }
+
+    describe "creating entity references" do
+      it "creates an entity reference node" do
+        doc = ctx.create_document
+        ref = doc.create_entity_reference("nbsp")
+        expect(ref).to be_a(Moxml::EntityReference)
+        expect(ref.name).to eq("nbsp")
+      end
+
+      it "creates standard XML entity references" do
+        doc = ctx.create_document
+        %w[amp lt gt quot apos].each do |name|
+          ref = doc.create_entity_reference(name)
+          expect(ref.name).to eq(name)
+        end
+      end
+
+      it "raises ValidationError for invalid names" do
+        doc = ctx.create_document
+        expect do
+          doc.create_entity_reference("123invalid")
+        end.to raise_error(Moxml::ValidationError)
+      end
+
+      it "raises ValidationError for empty name" do
+        doc = ctx.create_document
+        expect do
+          doc.create_entity_reference("")
+        end.to raise_error(Moxml::ValidationError)
+      end
+    end
+
+    describe "node properties" do
+      it "has empty text content" do
+        doc = ctx.create_document
+        ref = doc.create_entity_reference("amp")
+        expect(ref.text).to eq("")
+        expect(ref.content).to eq("")
+      end
+
+      it "is recognized as entity_reference type" do
+        doc = ctx.create_document
+        ref = doc.create_entity_reference("copy")
+        expect(ref.entity_reference?).to be true
+      end
+    end
+
+    describe "serialization" do
+      it "serializes to entity syntax" do
+        doc = ctx.create_document
+        ref = doc.create_entity_reference("mdash")
+        expect(ref.to_xml).to eq("—")
+      end
+
+      it "serializes standard entities" do
+        doc = ctx.create_document
+        ref = doc.create_entity_reference("amp")
+        expect(ref.to_xml).to eq("&")
+      end
+    end
+
+    describe "adding to document" do
+      it "survives add_child and retrieval" do
+        doc = ctx.create_document
+        root = doc.create_element("p")
+        doc.root = root
+        ref = doc.create_entity_reference("nbsp")
+        root.add_child(ref)
+        children = root.children
+        expect(children.size).to be >= 1
+        entity_child = children.find { |c| c.is_a?(Moxml::EntityReference) }
+        expect(entity_child).not_to be_nil
+        expect(entity_child.name).to eq("nbsp")
+      end
+
+      it "serializes within a document" do
+        doc = ctx.create_document
+        root = doc.create_element("p")
+        doc.root = root
+        root.add_child(doc.create_text("before"))
+        root.add_child(doc.create_entity_reference("nbsp"))
+        root.add_child(doc.create_text("after"))
+        output = doc.to_xml
+        expect(output).to include(" ")
+      end
+
+      it "preserves multiple entity references in sequence" do
+        doc = ctx.create_document
+        root = doc.create_element("p")
+        doc.root = 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"))
+        output = doc.to_xml
+        expect(output).to include(" ")
+        expect(output).to include("©")
+        expect(output).to include("—")
+      end
+    end
+  end
+end
+
+RSpec.describe Moxml::EntityReference do
+  %i[nokogiri oga ox rexml].each do |adapter_name|
+    it_behaves_like "entity reference node", adapter_name
+  end
+end

data/spec/moxml/entity_registry_spec.rb

@@ -181,4 +181,72 @@ RSpec.describe Moxml::EntityRegistry do
       expect(registry.load_all).to be(registry)
     end
   end
+
+  describe "#standard_entity?" do
+    it "returns true for the 5 standard XML entities" do
+      registry = described_class.new
+      expect(registry.standard_entity?(0x26)).to be true  # amp
+      expect(registry.standard_entity?(0x3C)).to be true  # lt
+      expect(registry.standard_entity?(0x3E)).to be true  # gt
+      expect(registry.standard_entity?(0x22)).to be true  # quot
+      expect(registry.standard_entity?(0x27)).to be true  # apos
+    end
+
+    it "returns false for non-standard codepoints" do
+      registry = described_class.new
+      expect(registry.standard_entity?(0xA0)).to be false   # nbsp
+      expect(registry.standard_entity?(0xA9)).to be false   # copy
+      expect(registry.standard_entity?(0x30)).to be false   # '0'
+    end
+  end
+
+  describe "#should_restore?" do
+    it "always restores the 5 standard XML entities regardless of config" do
+      registry = described_class.new
+      config = Moxml::Config.new(:nokogiri)
+      config.restore_entities = false
+      expect(registry.should_restore?(0x26, config: config)).to be true  # amp
+      expect(registry.should_restore?(0x3C, config: config)).to be true  # lt
+    end
+
+    it "restores non-standard entities when restore_entities is true and mode is lenient" do
+      registry = described_class.new
+      config = Moxml::Config.new(:nokogiri)
+      config.restore_entities = true
+      config.entity_restoration_mode = :lenient
+      expect(registry.should_restore?(0xA0, config: config)).to be true  # nbsp
+      expect(registry.should_restore?(0xA9, config: config)).to be true  # copy
+    end
+
+    it "does not restore non-standard entities when restore_entities is false" do
+      registry = described_class.new
+      config = Moxml::Config.new(:nokogiri)
+      config.restore_entities = false
+      expect(registry.should_restore?(0xA0, config: config)).to be false
+    end
+
+    it "returns false for codepoints not in the registry" do
+      registry = described_class.new(mode: :disabled)
+      config = Moxml::Config.new(:nokogiri)
+      config.restore_entities = true
+      expect(registry.should_restore?(0x30, config: config)).to be false # '0'
+    end
+  end
+
+  describe "#restorable_codepoints" do
+    it "returns the set of codepoints that could be restored" do
+      registry = described_class.new
+      codepoints = registry.restorable_codepoints
+      expect(codepoints).to be_a(Set)
+      expect(codepoints).to include(0x26)  # amp
+      expect(codepoints).to include(0xA0)  # nbsp
+      expect(codepoints.size).to be > 100
+    end
+
+    it "returns only standard codepoints for empty registry" do
+      registry = described_class.new(mode: :disabled)
+      codepoints = registry.restorable_codepoints
+      expect(codepoints).to eq(described_class::STANDARD_CODEPOINTS)
+    end
+  end
 end

data/spec/moxml/moxml_spec.rb

@@ -2,6 +2,28 @@
 
 # spec/moxml_spec.rb
 RSpec.describe Moxml do
+  around do |example|
+    original_default = Moxml::Config.instance_variable_get(:@default)
+    original_default_adapter = Moxml::Config.instance_variable_get(:@default_adapter)
+
+    Moxml::Config.remove_instance_variable(:@default) if Moxml::Config.instance_variable_defined?(:@default)
+    Moxml::Config.remove_instance_variable(:@default_adapter) if Moxml::Config.instance_variable_defined?(:@default_adapter)
+
+    example.run
+  ensure
+    if original_default.nil?
+      Moxml::Config.remove_instance_variable(:@default) if Moxml::Config.instance_variable_defined?(:@default)
+    else
+      Moxml::Config.instance_variable_set(:@default, original_default)
+    end
+
+    if original_default_adapter.nil?
+      Moxml::Config.remove_instance_variable(:@default_adapter) if Moxml::Config.instance_variable_defined?(:@default_adapter)
+    else
+      Moxml::Config.instance_variable_set(:@default_adapter, original_default_adapter)
+    end
+  end
+
   it "has a version number" do
     expect(Moxml::VERSION).not_to be_nil
   end
@@ -34,6 +56,23 @@ RSpec.describe Moxml do
       expect(context.config.adapter_name).to eq(:nokogiri)
     end
 
+    it "defaults to oga on Opal" do
+      stub_const("RUBY_ENGINE", "opal")
+
+      context = described_class.new
+      expect(context.config.adapter_name).to eq(:oga)
+    end
+
+    it "prefers ox when it is already loaded" do
+      allow(Object).to receive(:const_defined?).and_call_original
+      allow(Object).to receive(:const_defined?).with(:Nokogiri).and_return(false)
+      allow(Object).to receive(:const_defined?).with(:Ox).and_return(true)
+      allow(Object).to receive(:const_defined?).with(:Oga).and_return(false)
+
+      context = described_class.new
+      expect(context.config.adapter_name).to eq(:ox)
+    end
+
     it "uses configured options from the block" do
       described_class.configure do |config|
         config.default_adapter = :oga

data/spec/moxml/xpath/axes_spec.rb

@@ -222,7 +222,6 @@ 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/_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,6 @@ 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/_pages/headed-ox-limitations.adoc"
       ast = Moxml::XPath::Parser.parse("//*")
       proc = described_class.compile_with_cache(ast)
       result = proc.call(nested_doc)
@@ -189,7 +188,6 @@ RSpec.describe Moxml::XPath::Compiler do
     end
 
     it "works with wildcards" do
-      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/performance/benchmark_spec.rb

@@ -27,7 +27,7 @@ RSpec.shared_examples "Performance Examples" do
         {
           nokogiri: { parser: 15, serializer: 1000 },
           oga: { parser: 10, serializer: 100 },
-          rexml: { parser: 0, serializer: 60 },
+          rexml: { parser: 0, serializer: 5 },
           ox: { parser: 2, serializer: 1000 },
           headed_ox: { parser: 2, serializer: 1000 },
           libxml: { parser: 10, serializer: 30 },

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: moxml
 version: !ruby/object:Gem::Version
-  version: 0.1.16
+  version: 0.1.18
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-04-22 00:00:00.000000000 Z
+date: 2026-04-27 00:00:00.000000000 Z
 dependencies: []
 description: |
   Moxml is a unified XML manipulation library that provides a common API
@@ -34,16 +34,6 @@ files:
 - LICENSE.md
 - README.adoc
 - Rakefile
-- TODO.remaining/1-entity-reference-adapter-support.md
-- TODO.remaining/2-entity-restoration-model-driven.md
-- TODO.remaining/3-entity-reference-test-coverage.md
-- TODO.remaining/4-lenient-entities-mode.md
-- TODO.remaining/5-fixture-integrity.md
-- TODO.remaining/6-ox-element-ordering-bug.md
-- TODO.remaining/7-headed-ox-limitations.md
-- TODO.remaining/8-xpath-predicate-gaps.md
-- TODO.remaining/9-cleanup-hygiene.md
-- TODO.remaining/README.md
 - benchmarks/.gitignore
 - benchmarks/generate_report.rb
 - bin/console
@@ -277,6 +267,7 @@ files:
 - spec/integration/all_adapters_spec.rb
 - spec/integration/headed_ox_integration_spec.rb
 - spec/integration/shared_examples/edge_cases.rb
+- spec/integration/shared_examples/entity_reference_whitespace.rb
 - spec/integration/shared_examples/high_level/.gitkeep
 - spec/integration/shared_examples/high_level/builder_behavior.rb
 - spec/integration/shared_examples/high_level/context_behavior.rb
@@ -302,6 +293,7 @@ files:
 - spec/moxml/adapter/.gitkeep
 - spec/moxml/adapter/README.md
 - spec/moxml/adapter/base_spec.rb
+- spec/moxml/adapter/entity_restoration_spec.rb
 - spec/moxml/adapter/headed_ox_spec.rb
 - spec/moxml/adapter/libxml_spec.rb
 - spec/moxml/adapter/nokogiri_spec.rb
@@ -325,6 +317,8 @@ files:
 - spec/moxml/document_builder_spec.rb
 - spec/moxml/document_spec.rb
 - spec/moxml/element_spec.rb
+- spec/moxml/entity_preservation_spec.rb
+- spec/moxml/entity_reference_spec.rb
 - spec/moxml/entity_registry_spec.rb
 - spec/moxml/error_spec.rb
 - spec/moxml/lazy_parse_spec.rb

data/TODO.remaining/1-entity-reference-adapter-support.md

@@ -1,157 +0,0 @@
-# TODO 1: EntityReference Adapter Support for Ox, Oga, REXML, LibXML, HeadedOx
-
-## Problem
-
-Only the Nokogiri adapter implements `create_native_entity_reference` and maps
-its native type to `:entity_reference` in `node_type`. The other 5 adapters
-will raise `NotImplementedError` if `restore_entities` is enabled or if any
-code path calls `create_entity_reference`. This makes the entire
-EntityReference feature **non-functional** outside Nokogiri.
-
-## Current State (verified)
-
-| Adapter   | `create_native_entity_reference` | `node_type` mapping | Serialization | Status |
-|-----------|----------------------------------|---------------------|---------------|--------|
-| Nokogiri  | Done (`Nokogiri::XML::EntityReference.new`) | Done | Native | Working |
-| Ox        | Missing | Missing | Uses `Ox.dump` (C-level, won't handle custom types) | Broken |
-| HeadedOx  | Missing (inherits Ox) | Missing | Same as Ox | Broken |
-| Oga       | Missing | Missing | Uses `CustomizedOga::XmlGenerator` | Broken |
-| REXML     | Missing | Missing | Uses REXML's `write` | Broken |
-| LibXML    | Missing | Missing | Uses custom serializer with wrapper detection | Broken |
-
-## Architecture
-
-EntityReference follows the same pattern as other non-native node types in Moxml:
-a **wrapper class** that represents what the underlying library cannot express natively.
-
-Each adapter needs three things:
-1. **Wrapper class** (`CustomizedXxx::EntityReference`) — holds the entity name
-2. **`node_type` mapping** — so `Node.wrap` can create the correct Moxml type
-3. **Serialization** — so `to_xml` outputs `&name;`
-
-The existing pattern: `CustomizedOx::Text` extends `::Ox::Node`,
-`CustomizedOx::Attribute` extends `::Ox::Node`. EntityReference should follow suit.
-
-### Serialization Challenge for Ox
-
-Ox's `serialize` calls `::Ox.dump(node)` which is C-level — it only handles
-Ox native types. For EntityReference wrappers to survive serialization, we need
-one of:
-
-- **Option A**: Custom serialization in the adapter that walks the tree manually,
-  detecting EntityReference wrappers and emitting `&name;` directly.
-- **Option B**: Convert EntityReferences to their text equivalent before calling
-  `Ox.dump`, restoring them in a post-processing step. This is fragile.
-- **Option C**: Override `serialize` for Element nodes to handle children
-  individually, using `Ox.dump` for native children but handling wrappers
-  directly.
-
-**Recommended: Option A** — it's how `CustomizedOga::XmlGenerator` already works
-for Oga. A similar tree-walking serializer for Ox gives full control.
-
-For LibXML, the existing serializer already checks `node.respond_to?(:to_xml)`
-for wrapper classes, so adding an EntityReference wrapper with `to_xml` returning
-`"&#{name};"` should integrate cleanly.
-
-## Implementation Steps
-
-### Ox Adapter
-
-1. Create `lib/moxml/adapter/customized_ox/entity_reference.rb`:
-   ```ruby
-   module Moxml::Adapter::CustomizedOx
-     class EntityReference < ::Ox::Node
-       attr_reader :name
-
-       def initialize(name)
-         @name = name
-         super()  # Ox::Node requires no args or a value
-       end
-
-       def to_xml
-         "&#{@name};"
-       end
-       alias to_s to_xml
-     end
-   end
-   ```
-
-2. Add to `lib/moxml/adapter/ox.rb`:
-   - `create_native_entity_reference(name)` → `CustomizedOx::EntityReference.new(name)`
-   - `node_type`: add `when CustomizedOx::EntityReference then :entity_reference`
-   - `patch_node`: handle EntityReference wrapper in child list
-   - `entity_reference_name(node)`: return `node.name`
-   - Serialization: handle EntityReference children when walking the tree
-
-3. Add to `lib/moxml/adapter/ox.rb` `unpatch_node`: return wrapper as-is
-   (it extends Ox::Node so it can stay in the tree)
-
-### HeadedOx Adapter
-
-HeadedOx inherits from Ox, so it gets Ox's EntityReference support
-automatically once Ox is done. Verify that the XPath engine doesn't
-break when encountering EntityReference nodes in the tree.
-
-### Oga Adapter
-
-1. Create `lib/moxml/adapter/customized_oga/entity_reference.rb`:
-   ```ruby
-   module Moxml::Adapter::CustomizedOga
-     class EntityReference
-       attr_reader :name
-
-       def initialize(name)
-         @name = name
-       end
-
-       def to_xml
-         "&#{@name};"
-       end
-     end
-   end
-   ```
-
-2. Add to `lib/moxml/adapter/oga.rb`:
-   - `create_native_entity_reference(name)` → `CustomizedOga::EntityReference.new(name)`
-   - `node_type`: add `when CustomizedOga::EntityReference then :entity_reference`
-   - Update `CustomizedOga::XmlGenerator` to handle EntityReference children
-   - `entity_reference_name(node)`: return `node.name`
-
-### REXML Adapter
-
-1. Investigate: REXML has `REXML::Entity` and `REXML::EntityRef` classes.
-   Check if they can be used as native entity reference nodes, or if a
-   wrapper is needed.
-
-2. Add to `lib/moxml/adapter/rexml.rb`:
-   - `create_native_entity_reference(name)` — native or wrapper
-   - `node_type`: add mapping
-   - `entity_reference_name(node)`
-
-### LibXML Adapter
-
-1. Investigate: LibXML Ruby has `LibXML::XML::Node::ENTITY_REF_NODE` constant
-   (value 5). Check if native entity reference nodes can be created.
-
-2. Create `lib/moxml/adapter/customized_libxml/entity_reference.rb` if needed.
-
-3. Add to `lib/moxml/adapter/libxml.rb`:
-   - `create_native_entity_reference(name)`
-   - `node_type`: add `ENTITY_REF_NODE` mapping or wrapper mapping
-   - `entity_reference_name(node)`
-   - The existing serializer already handles wrappers with `to_xml` —
-     verify EntityReference works in this path.
-
-## Files to Create/Modify
-
-### New Files
-- `lib/moxml/adapter/customized_ox/entity_reference.rb`
-- `lib/moxml/adapter/customized_oga/entity_reference.rb`
-- Possibly: `lib/moxml/adapter/customized_libxml/entity_reference.rb`
-
-### Modified Files
-- `lib/moxml/adapter/ox.rb` — create_native_entity_reference, node_type, serialization
-- `lib/moxml/adapter/oga.rb` — create_native_entity_reference, node_type, XmlGenerator
-- `lib/moxml/adapter/rexml.rb` — create_native_entity_reference, node_type
-- `lib/moxml/adapter/libxml.rb` — create_native_entity_reference, node_type
-- `lib/moxml/adapter/headed_ox.rb` — verify inheritance works (likely no changes)