moxml 0.1.14 → 0.1.16

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c46c9d241e38351b1547ab8be8297ff2902886f022ccdfb3fc2f196d2594bf2b
-  data.tar.gz: b1d34fb4306d96d940afea932d5d9f6c6bcffc74c6715e00a6f622302be2f878
+  metadata.gz: 378f1400934e3a65fb230779fc4b1783aab059efb449912a6dc2d97c8d82903e
+  data.tar.gz: 7cd2739dd2dc41c2edb69c129cc4ec175a7a6b8e455d4d63cfd56bd2a93e808f
 SHA512:
-  metadata.gz: 9178c13199c195aa0b3ed628d5837fa6c1fdaeaa3e3cc462a8520a89ad6bb98963ff0a9c2b668038ff27a0653e2aa2fba98ce1c8bc10eccc74abab0daa26e455
-  data.tar.gz: 5b1b06dea56ac0b28dd2b8ca072fa554039936c336e6b262430d40f45ab2972b1e6bf38f3c13cf192c9fc2a9cc9fe827abc99aa662d30ebdaae97d361d981475
+  metadata.gz: 311f4905dcf14fb3ec209491d9a5eae9b8fe460152f29c7f7b428db37b1c2adac09e538ce9c0a8a4eeff2b0af83a2e8b4a787adca59cb04d1c7f1b14b7fbf37d
+  data.tar.gz: 36cc3ce0e2328547137f1716d7b7ef3de4e07cbca160b08d8fbe74ef126edd6e61fe4dc0ed1d8767ed19f573792fc8fdc52c41e332802698218584db559576e0

data/.rubocop_todo.yml

@@ -1,96 +1,97 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-04-05 03:01:25 UTC using RuboCop version 1.86.0.
+# on 2026-04-22 01:41:34 UTC using RuboCop version 1.86.0.
 # The point is for the user to remove these configuration records
 # one by one as the offenses are removed from the code base.
 # Note that changes in the inspected code, or installation of new
 # versions of RuboCop, may require this file to be generated again.
 
-# Offense count: 5
+# Offense count: 18
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, IndentationWidth.
 # SupportedStyles: with_first_argument, with_fixed_indentation
 Layout/ArgumentAlignment:
   Exclude:
-    - 'lib/moxml/config.rb'
-    - 'lib/moxml/entity_registry.rb'
-    - 'spec/moxml/entity_registry_spec.rb'
+    - 'spec/moxml/allocation_benchmark_spec.rb'
+    - 'spec/moxml/allocation_guard_spec.rb'
 
-# Offense count: 1
+# Offense count: 14
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyleAlignWith.
 # SupportedStylesAlignWith: either, start_of_block, start_of_line
 Layout/BlockAlignment:
   Exclude:
-    - 'spec/moxml/config_spec.rb'
+    - 'lib/moxml/adapter/ox.rb'
+    - 'spec/moxml/allocation_benchmark_spec.rb'
+    - 'spec/moxml/allocation_guard_spec.rb'
+    - 'spec/moxml/lazy_parse_spec.rb'
+    - 'spec/moxml/node_cache_spec.rb'
 
-# Offense count: 1
+# Offense count: 7
 # This cop supports safe autocorrection (--autocorrect).
 Layout/BlockEndNewline:
   Exclude:
-    - 'spec/moxml/config_spec.rb'
+    - 'lib/moxml/adapter/ox.rb'
+    - 'spec/moxml/allocation_benchmark_spec.rb'
+    - 'spec/moxml/allocation_guard_spec.rb'
+    - 'spec/moxml/lazy_parse_spec.rb'
+    - 'spec/moxml/node_cache_spec.rb'
 
-# Offense count: 1
+# Offense count: 3
 # This cop supports safe autocorrection (--autocorrect).
 Layout/ClosingParenthesisIndentation:
   Exclude:
-    - 'spec/moxml/entity_registry_spec.rb'
+    - 'spec/moxml/allocation_guard_spec.rb'
 
-# Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-Layout/EmptyLineAfterGuardClause:
-  Exclude:
-    - 'lib/moxml/config.rb'
-
-# Offense count: 1
+# Offense count: 3
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, IndentationWidth.
 # SupportedStyles: consistent, consistent_relative_to_receiver, special_for_inner_method_call, special_for_inner_method_call_in_parentheses
 Layout/FirstArgumentIndentation:
   Exclude:
-    - 'spec/moxml/entity_registry_spec.rb'
-
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowMultipleStyles, EnforcedHashRocketStyle, EnforcedColonStyle, EnforcedLastArgumentHashStyle.
-# SupportedHashRocketStyles: key, separator, table
-# SupportedColonStyles: key, separator, table
-# SupportedLastArgumentHashStyles: always_inspect, always_ignore, ignore_implicit, ignore_explicit
-Layout/HashAlignment:
-  Exclude:
-    - 'spec/moxml/entity_registry_spec.rb'
+    - 'spec/moxml/allocation_guard_spec.rb'
 
-# Offense count: 2
+# Offense count: 13
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Width, EnforcedStyleAlignWith, AllowedPatterns.
 # SupportedStylesAlignWith: start_of_line, relative_to_receiver
 Layout/IndentationWidth:
   Exclude:
-    - 'spec/moxml/config_spec.rb'
+    - 'lib/moxml/adapter/ox.rb'
+    - 'spec/moxml/allocation_benchmark_spec.rb'
+    - 'spec/moxml/allocation_guard_spec.rb'
+    - 'spec/moxml/lazy_parse_spec.rb'
+    - 'spec/moxml/node_cache_spec.rb'
 
-# Offense count: 238
+# Offense count: 307
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: Max, AllowHeredoc, AllowURI, AllowQualifiedName, URISchemes, AllowRBSInlineAnnotation, AllowCopDirectives, AllowedPatterns, SplitStrings.
 # URISchemes: http, https
 Layout/LineLength:
   Enabled: false
 
-# Offense count: 1
+# Offense count: 3
+# This cop supports safe autocorrection (--autocorrect).
+Layout/MultilineBlockLayout:
+  Exclude:
+    - 'spec/moxml/allocation_benchmark_spec.rb'
+    - 'spec/moxml/allocation_guard_spec.rb'
+
+# Offense count: 3
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle.
 # SupportedStyles: symmetrical, new_line, same_line
 Layout/MultilineMethodCallBraceLayout:
   Exclude:
-    - 'spec/moxml/entity_registry_spec.rb'
+    - 'spec/moxml/allocation_guard_spec.rb'
 
-# Offense count: 4
+# Offense count: 3
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: AllowInHeredoc.
 Layout/TrailingWhitespace:
   Exclude:
-    - 'lib/moxml/config.rb'
-    - 'lib/moxml/entity_registry.rb'
-    - 'spec/moxml/entity_registry_spec.rb'
+    - 'spec/moxml/allocation_benchmark_spec.rb'
+    - 'spec/moxml/allocation_guard_spec.rb'
 
 # Offense count: 7
 # Configuration parameters: AllowedMethods.
@@ -100,26 +101,28 @@ Lint/ConstantDefinitionInBlock:
     - 'spec/moxml/declaration_preservation_spec.rb'
     - 'spec/moxml/sax_spec.rb'
 
-# Offense count: 6
+# Offense count: 8
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
   Exclude:
     - 'benchmarks/generate_report.rb'
     - 'lib/moxml/adapter/customized_libxml/declaration.rb'
     - 'lib/moxml/adapter/libxml.rb'
+    - 'lib/moxml/adapter/ox.rb'
     - 'lib/moxml/document.rb'
 
-# Offense count: 3
+# Offense count: 4
 Lint/DuplicateMethods:
   Exclude:
     - 'lib/moxml/config.rb'
     - 'lib/moxml/element.rb'
     - 'lib/moxml/node.rb'
 
-# Offense count: 2
+# Offense count: 4
 # Configuration parameters: AllowComments, AllowEmptyLambdas.
 Lint/EmptyBlock:
   Exclude:
+    - 'spec/moxml/allocation_benchmark_spec.rb'
     - 'spec/moxml/xpath/axes_spec.rb'
 
 # Offense count: 1
@@ -153,7 +156,7 @@ Lint/NoReturnInBeginEndBlocks:
   Exclude:
     - 'examples/api_client/api_client.rb'
 
-# Offense count: 97
+# Offense count: 100
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
@@ -169,12 +172,12 @@ Metrics/BlockLength:
 Metrics/BlockNesting:
   Max: 4
 
-# Offense count: 65
+# Offense count: 70
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 170
+# Offense count: 182
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 110
@@ -184,11 +187,19 @@ Metrics/MethodLength:
 Metrics/ParameterLists:
   Max: 7
 
-# Offense count: 44
+# Offense count: 47
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/PerceivedComplexity:
   Enabled: false
 
+# Offense count: 2
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: EnforcedStyleForLeadingUnderscores.
+# SupportedStylesForLeadingUnderscores: disallowed, required, optional
+Naming/MemoizedInstanceVariableName:
+  Exclude:
+    - 'lib/moxml/element.rb'
+
 # Offense count: 16
 # Configuration parameters: MinNameLength, AllowNamesEndingInNumbers, AllowedNames, ForbiddenNames.
 # AllowedNames: as, at, by, cc, db, id, if, in, io, ip, of, on, os, pp, to
@@ -213,6 +224,33 @@ Naming/PredicateMethod:
     - 'lib/moxml/config.rb'
     - 'lib/moxml/xpath/ruby/node.rb'
 
+# Offense count: 10
+# Configuration parameters: EnforcedStyle, CheckMethodNames, CheckSymbols, AllowedIdentifiers, AllowedPatterns.
+# SupportedStyles: snake_case, normalcase, non_integer
+# AllowedIdentifiers: TLS1_1, TLS1_2, capture3, iso8601, rfc1123_date, rfc822, rfc2822, rfc3339, x86_64
+Naming/VariableNumber:
+  Exclude:
+    - 'spec/moxml/allocation_guard_spec.rb'
+    - 'spec/support/allocation_helper.rb'
+
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Performance/TimesMap:
+  Exclude:
+    - 'spec/support/allocation_helper.rb'
+
+# Offense count: 5
+RSpec/BeforeAfterAll:
+  Exclude:
+    - '**/spec/spec_helper.rb'
+    - '**/spec/rails_helper.rb'
+    - '**/spec/support/**/*.rb'
+    - 'spec/moxml/allocation_benchmark_spec.rb'
+    - 'spec/moxml/allocation_guard_spec.rb'
+    - 'spec/moxml/lazy_parse_spec.rb'
+    - 'spec/moxml/node_cache_spec.rb'
+    - 'spec/moxml/node_set_cache_spec.rb'
+
 # Offense count: 46
 # Configuration parameters: Prefixes, AllowedPatterns.
 # Prefixes: when, with, without
@@ -226,12 +264,12 @@ RSpec/ContextWording:
     - 'spec/moxml/xpath/parser_spec.rb'
     - 'spec/performance/benchmark_spec.rb'
 
-# Offense count: 16
+# Offense count: 23
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Enabled: false
 
-# Offense count: 233
+# Offense count: 271
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 64
@@ -267,11 +305,11 @@ RSpec/LeakyConstantDeclaration:
 RSpec/MessageSpies:
   EnforcedStyle: receive
 
-# Offense count: 327
+# Offense count: 356
 RSpec/MultipleExpectations:
   Max: 10
 
-# Offense count: 2
+# Offense count: 4
 # Configuration parameters: AllowSubject.
 RSpec/MultipleMemoizedHelpers:
   Max: 7
@@ -333,7 +371,7 @@ Security/Eval:
   Exclude:
     - 'spec/moxml/xpath/ruby/generator_spec.rb'
 
-# Offense count: 3
+# Offense count: 11
 # This cop supports safe autocorrection (--autocorrect).
 # Configuration parameters: EnforcedStyle, ProceduralMethods, FunctionalMethods, AllowedMethods, AllowedPatterns, AllowBracesOnProceduralOneLiners, BracesRequiredMethods.
 # SupportedStyles: line_count_based, semantic, braces_for_chaining, always_braces
@@ -342,8 +380,11 @@ Security/Eval:
 # AllowedMethods: lambda, proc, it
 Style/BlockDelimiters:
   Exclude:
-    - 'spec/moxml/config_spec.rb'
-    - 'spec/moxml/entity_registry_spec.rb'
+    - 'lib/moxml/adapter/ox.rb'
+    - 'spec/moxml/allocation_benchmark_spec.rb'
+    - 'spec/moxml/allocation_guard_spec.rb'
+    - 'spec/moxml/lazy_parse_spec.rb'
+    - 'spec/moxml/node_cache_spec.rb'
 
 # Offense count: 1
 Style/DocumentDynamicEvalDefinition:
@@ -356,28 +397,32 @@ Style/EvalWithLocation:
   Exclude:
     - 'spec/moxml/xpath/ruby/generator_spec.rb'
 
-# Offense count: 2
+# Offense count: 4
 # Configuration parameters: MinBranchesCount.
 Style/HashLikeCase:
   Exclude:
     - 'lib/moxml/adapter/customized_rexml/formatter.rb'
+    - 'lib/moxml/adapter/ox.rb'
 
 # Offense count: 1
-Style/MissingRespondToMissing:
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Style/MapToHash:
   Exclude:
-    - 'lib/moxml/xpath/ruby/node.rb'
+    - 'spec/moxml/node_cache_spec.rb'
 
-# Offense count: 2
-# This cop supports safe autocorrection (--autocorrect).
-Style/MultilineIfModifier:
+# Offense count: 1
+Style/MissingRespondToMissing:
   Exclude:
-    - 'lib/moxml/entity_registry.rb'
+    - 'lib/moxml/xpath/ruby/node.rb'
 
 # Offense count: 1
-# This cop supports safe autocorrection (--autocorrect).
-Style/NilLambda:
+# This cop supports unsafe autocorrection (--autocorrect-all).
+# Configuration parameters: EnforcedStyle, AllowedMethods, AllowedPatterns.
+# SupportedStyles: predicate, comparison
+Style/NumericPredicate:
   Exclude:
-    - 'spec/moxml/entity_registry_spec.rb'
+    - 'spec/**/*'
+    - 'lib/moxml/node_set.rb'
 
 # Offense count: 5
 # Configuration parameters: AllowedClasses.
@@ -395,10 +440,16 @@ Style/OptionalBooleanParameter:
     - 'lib/moxml/adapter/libxml.rb'
     - 'lib/moxml/xpath/compiler.rb'
 
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Style/SelectByKind:
+  Exclude:
+    - 'lib/moxml/adapter/ox.rb'
+
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyleForMultiline.
-# SupportedStylesForMultiline: comma, consistent_comma, diff_comma, no_comma
-Style/TrailingCommaInArguments:
+# Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
+# SupportedStyles: single_quotes, double_quotes
+Style/StringLiterals:
   Exclude:
-    - 'lib/moxml/context.rb'
+    - 'spec/moxml/lazy_parse_spec.rb'

data/Gemfile

@@ -22,6 +22,7 @@ gem "rubocop-performance"
 gem "rubocop-rake"
 gem "rubocop-rspec"
 gem "simplecov", require: false
+gem "stackprof"
 gem "tempfile"
 
 # Needed by get_process_mem on Windows

data/README.adoc

@@ -815,25 +815,27 @@ context = Moxml.new do |config|
 end
 ----
 
-=== Namespace URI validation
+=== Namespace validation
 
 Moxml validates namespace URIs against
-https://www.rfc-editor.org/rfc/rfc3986[RFC 3986] by default, as required by the
-https://www.w3.org/TR/xml-names/[W3C Namespaces in XML] specification.
+https://www.rfc-editor.org/rfc/rfc3986[RFC 3986] and namespace prefixes against
+the https://www.w3.org/TR/xml-names/[W3C Namespaces in XML] NCName production
+rules by default.
 
-For documents that use non-standard namespace identifiers, a lenient mode is
-available:
+For documents that use non-standard namespace identifiers or prefixes, a lenient
+mode is available:
 
 [source,ruby]
 ----
-# Strict mode (default) — rejects invalid URIs per RFC 3986
+# Strict mode (default) — validates URI per RFC 3986 and prefix per NCName rules
 context = Moxml.new do |config|
-  config.namespace_uri_mode = :strict
+  config.namespace_validation_mode = :strict
 end
 
-# Lenient mode — accepts any string as a namespace URI
+# Lenient mode — accepts any URI string and defers prefix validation to the
+# underlying XML parser
 context = Moxml.new do |config|
-  config.namespace_uri_mode = :lenient
+  config.namespace_validation_mode = :lenient
 end
 ----
 

data/Rakefile

@@ -10,6 +10,37 @@ require "rubocop/rake_task"
 RuboCop::RakeTask.new
 
 namespace :spec do
+  desc "Validate XML fixtures are well-formed (requires xmllint)"
+  task :validate_fixtures do
+    fixtures = Dir.glob("spec/fixtures/**/*.xml")
+    if fixtures.empty?
+      abort "No XML fixtures found in spec/fixtures/"
+    end
+
+    unless system("which xmllint > /dev/null 2>&1")
+      abort "xmllint not found. Install with: brew install libxml2 (macOS) or apt install libxml2-utils (Linux)"
+    end
+
+    # Intentionally malformed fixtures (W3C test cases for error handling)
+    exemptions = %w[
+      spec/fixtures/w3c/namespaces/1.0/035.xml
+    ]
+
+    errors = []
+    fixtures.each do |path|
+      next if exemptions.include?(path)
+
+      output = `xmllint --noout "#{path}" 2>&1`
+      errors << "#{path}: #{output.strip}" unless $?.success?
+    end
+
+    if errors.empty?
+      puts "#{fixtures.size} XML fixtures validated OK"
+    else
+      abort "Invalid fixtures:\n#{errors.join("\n")}"
+    end
+  end
+
   desc "Run unit tests only"
   RSpec::Core::RakeTask.new(:unit) do |t|
     t.pattern = "spec/unit/**/*_spec.rb"
@@ -36,7 +67,9 @@ namespace :spec do
       categories = ENV.fetch("CATEGORIES", "").split(",").map(&:strip)
       abort "Usage: CATEGORIES=metanorma,rfcxml rake spec:consistency:by_category" if categories.empty?
 
-      include_filters = categories.map { |c| "--tag fixture_category:#{c}" }.join(" ")
+      include_filters = categories.map do |c|
+        "--tag fixture_category:#{c}"
+      end.join(" ")
       sh "bundle exec rspec spec/consistency/ --tag round_trip #{include_filters}"
     end
   end

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

@@ -0,0 +1,157 @@
+# 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)