moxml 0.1.16 → 0.1.17

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 378f1400934e3a65fb230779fc4b1783aab059efb449912a6dc2d97c8d82903e
-  data.tar.gz: 7cd2739dd2dc41c2edb69c129cc4ec175a7a6b8e455d4d63cfd56bd2a93e808f
+  metadata.gz: bbd69145e9a360635af848bf0bdda2883e35760b2763021f6bf6f1d6dca9827e
+  data.tar.gz: aa492e21514fd80a01f98709eddf8c3aa323b584210d56534ad5e2c2b467df18
 SHA512:
-  metadata.gz: 311f4905dcf14fb3ec209491d9a5eae9b8fe460152f29c7f7b428db37b1c2adac09e538ce9c0a8a4eeff2b0af83a2e8b4a787adca59cb04d1c7f1b14b7fbf37d
-  data.tar.gz: 36cc3ce0e2328547137f1716d7b7ef3de4e07cbca160b08d8fbe74ef126edd6e61fe4dc0ed1d8767ed19f573792fc8fdc52c41e332802698218584db559576e0
+  metadata.gz: 1cdb7d6c934f1ea788a40d81d987c97d4c1fc21ad71d22eaac73abf45d093680667f3303b35934378b8cce0d99e3fc9db47c85632678247426527d7fb3491bed
+  data.tar.gz: 79c352eb8df9b86831d554e17538abd4da8a6dfce61b4e566bc236334601e43bff7c670894ea05c72abac40bb1b3b90375ef8caaf6b488a9c43bc33fc70d6785

data/.gitignore

@@ -28,6 +28,9 @@ libxml_*.txt
 # Generated benchmark reports (machine-specific)
 /benchmarks/PERFORMANCE_REPORT.md
 
+# Local TODO tracking (kept locally, not committed)
+TODO*
+
 # IDE and editor files
 .vscode/
 .idea/
@@ -49,3 +52,6 @@ libxml_*.txt
 /_site
 /docs/_site
 /docs/.jekyll-cache
+
+# Utility scripts (local only)
+/scripts/

data/.rubocop_todo.yml

@@ -1,97 +1,46 @@
 # This configuration was generated by
 # `rubocop --auto-gen-config`
-# on 2026-04-22 01:41:34 UTC using RuboCop version 1.86.0.
+# on 2026-04-23 07:48:23 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: 18
-# This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, IndentationWidth.
-# SupportedStyles: with_first_argument, with_fixed_indentation
-Layout/ArgumentAlignment:
-  Exclude:
-    - 'spec/moxml/allocation_benchmark_spec.rb'
-    - 'spec/moxml/allocation_guard_spec.rb'
-
-# Offense count: 14
+# Offense count: 4
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyleAlignWith.
-# SupportedStylesAlignWith: either, start_of_block, start_of_line
-Layout/BlockAlignment:
+Layout/EmptyLineAfterGuardClause:
   Exclude:
-    - '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'
+    - 'lib/moxml/adapter/customized_rexml/formatter.rb'
+    - 'lib/moxml/adapter/libxml.rb'
+    - 'lib/moxml/entity_registry.rb'
 
-# Offense count: 7
+# Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
-Layout/BlockEndNewline:
+# Configuration parameters: EmptyLineBetweenMethodDefs, EmptyLineBetweenClassDefs, EmptyLineBetweenModuleDefs, DefLikeMacros, AllowAdjacentOneLineDefs, NumberOfEmptyLines.
+Layout/EmptyLineBetweenDefs:
   Exclude:
     - '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: 3
-# This cop supports safe autocorrection (--autocorrect).
-Layout/ClosingParenthesisIndentation:
-  Exclude:
-    - 'spec/moxml/allocation_guard_spec.rb'
-
-# 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/allocation_guard_spec.rb'
-
-# Offense count: 13
+# Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: Width, EnforcedStyleAlignWith, AllowedPatterns.
-# SupportedStylesAlignWith: start_of_line, relative_to_receiver
-Layout/IndentationWidth:
+Layout/EmptyLines:
   Exclude:
     - '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: 307
+# Offense count: 330
 # 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: 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/allocation_guard_spec.rb'
-
-# Offense count: 3
+# Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: AllowInHeredoc.
-Layout/TrailingWhitespace:
+# Configuration parameters: EnforcedStyle, IndentationWidth.
+# SupportedStyles: aligned, indented
+Layout/MultilineOperationIndentation:
   Exclude:
-    - 'spec/moxml/allocation_benchmark_spec.rb'
-    - 'spec/moxml/allocation_guard_spec.rb'
+    - 'lib/moxml/adapter/ox.rb'
 
 # Offense count: 7
 # Configuration parameters: AllowedMethods.
@@ -101,7 +50,7 @@ Lint/ConstantDefinitionInBlock:
     - 'spec/moxml/declaration_preservation_spec.rb'
     - 'spec/moxml/sax_spec.rb'
 
-# Offense count: 8
+# Offense count: 10
 # Configuration parameters: IgnoreLiteralBranches, IgnoreConstantBranches, IgnoreDuplicateElseBranch.
 Lint/DuplicateBranch:
   Exclude:
@@ -110,8 +59,9 @@ Lint/DuplicateBranch:
     - 'lib/moxml/adapter/libxml.rb'
     - 'lib/moxml/adapter/ox.rb'
     - 'lib/moxml/document.rb'
+    - 'lib/moxml/entity_registry.rb'
 
-# Offense count: 4
+# Offense count: 5
 Lint/DuplicateMethods:
   Exclude:
     - 'lib/moxml/config.rb'
@@ -138,6 +88,11 @@ Lint/EmptyWhen:
   Exclude:
     - 'lib/moxml/xpath/compiler.rb'
 
+# Offense count: 3
+Lint/HashCompareByIdentity:
+  Exclude:
+    - 'lib/moxml/native_attachment.rb'
+
 # Offense count: 1
 Lint/IneffectiveAccessModifier:
   Exclude:
@@ -156,28 +111,28 @@ Lint/NoReturnInBeginEndBlocks:
   Exclude:
     - 'examples/api_client/api_client.rb'
 
-# Offense count: 100
+# Offense count: 104
 # Configuration parameters: AllowedMethods, AllowedPatterns, CountRepeatedAttributes, Max.
 Metrics/AbcSize:
   Enabled: false
 
-# Offense count: 7
+# Offense count: 8
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns, inherit_mode.
 # AllowedMethods: refine
 Metrics/BlockLength:
   Max: 90
 
-# Offense count: 5
+# Offense count: 7
 # Configuration parameters: CountBlocks, CountModifierForms.
 Metrics/BlockNesting:
   Max: 4
 
-# Offense count: 70
+# Offense count: 76
 # Configuration parameters: AllowedMethods, AllowedPatterns, Max.
 Metrics/CyclomaticComplexity:
   Enabled: false
 
-# Offense count: 182
+# Offense count: 186
 # Configuration parameters: CountComments, CountAsOne, AllowedMethods, AllowedPatterns.
 Metrics/MethodLength:
   Max: 110
@@ -187,19 +142,11 @@ Metrics/MethodLength:
 Metrics/ParameterLists:
   Max: 7
 
-# Offense count: 47
+# Offense count: 52
 # 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
@@ -233,12 +180,6 @@ Naming/VariableNumber:
     - '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:
@@ -264,12 +205,12 @@ RSpec/ContextWording:
     - 'spec/moxml/xpath/parser_spec.rb'
     - 'spec/performance/benchmark_spec.rb'
 
-# Offense count: 23
+# Offense count: 24
 # Configuration parameters: IgnoredMetadata.
 RSpec/DescribeClass:
   Enabled: false
 
-# Offense count: 271
+# Offense count: 295
 # Configuration parameters: CountAsOne.
 RSpec/ExampleLength:
   Max: 64
@@ -305,7 +246,7 @@ RSpec/LeakyConstantDeclaration:
 RSpec/MessageSpies:
   EnforcedStyle: receive
 
-# Offense count: 356
+# Offense count: 390
 RSpec/MultipleExpectations:
   Max: 10
 
@@ -326,12 +267,6 @@ RSpec/NoExpectationExample:
   Exclude:
     - 'spec/performance/xpath_benchmark_spec.rb'
 
-# Offense count: 6
-RSpec/PendingWithoutReason:
-  Exclude:
-    - 'spec/moxml/xpath/functions/position_functions_spec.rb'
-    - 'spec/moxml/xpath/functions/special_functions_spec.rb'
-
 # Offense count: 4
 RSpec/RepeatedExample:
   Exclude:
@@ -371,21 +306,6 @@ Security/Eval:
   Exclude:
     - 'spec/moxml/xpath/ruby/generator_spec.rb'
 
-# 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
-# ProceduralMethods: benchmark, bm, bmbm, create, each_with_object, measure, new, realtime, tap, with_object
-# FunctionalMethods: let, let!, subject, watch
-# AllowedMethods: lambda, proc, it
-Style/BlockDelimiters:
-  Exclude:
-    - '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:
   Exclude:
@@ -404,25 +324,17 @@ Style/HashLikeCase:
     - 'lib/moxml/adapter/customized_rexml/formatter.rb'
     - 'lib/moxml/adapter/ox.rb'
 
-# Offense count: 1
-# This cop supports unsafe autocorrection (--autocorrect-all).
-Style/MapToHash:
-  Exclude:
-    - 'spec/moxml/node_cache_spec.rb'
-
 # Offense count: 1
 Style/MissingRespondToMissing:
   Exclude:
     - 'lib/moxml/xpath/ruby/node.rb'
 
 # Offense count: 1
-# This cop supports unsafe autocorrection (--autocorrect-all).
-# Configuration parameters: EnforcedStyle, AllowedMethods, AllowedPatterns.
-# SupportedStyles: predicate, comparison
-Style/NumericPredicate:
+# This cop supports safe autocorrection (--autocorrect).
+# Configuration parameters: AllowMethodComparison, ComparisonsThreshold.
+Style/MultipleComparison:
   Exclude:
-    - 'spec/**/*'
-    - 'lib/moxml/node_set.rb'
+    - 'lib/moxml/xpath/compiler.rb'
 
 # Offense count: 5
 # Configuration parameters: AllowedClasses.
@@ -440,16 +352,20 @@ Style/OptionalBooleanParameter:
     - 'lib/moxml/adapter/libxml.rb'
     - 'lib/moxml/xpath/compiler.rb'
 
-# Offense count: 1
-# This cop supports unsafe autocorrection (--autocorrect-all).
-Style/SelectByKind:
+# Offense count: 2
+# This cop supports safe autocorrection (--autocorrect).
+Style/RedundantAssignment:
   Exclude:
     - 'lib/moxml/adapter/ox.rb'
 
 # Offense count: 1
 # This cop supports safe autocorrection (--autocorrect).
-# Configuration parameters: EnforcedStyle, ConsistentQuotesInMultiline.
-# SupportedStyles: single_quotes, double_quotes
-Style/StringLiterals:
+Style/RedundantConstantBase:
   Exclude:
-    - 'spec/moxml/lazy_parse_spec.rb'
+    - 'spec/moxml/adapter/headed_ox_spec.rb'
+
+# Offense count: 1
+# This cop supports unsafe autocorrection (--autocorrect-all).
+Style/SelectByKind:
+  Exclude:
+    - 'spec/integration/shared_examples/node_wrappers/entity_reference_behavior.rb'

data/README.adoc

@@ -887,6 +887,18 @@ The Ox adapter provides maximum parsing speed but has XPath limitations.
 doc.xpath("//book").find { |book| book["id"] == "123" }
 ----
 
+**Upstream Ox gem limitations:**
+
+These limitations exist in the Ox gem itself and cannot be worked around in Moxml
+without changes to the Ox C extension:
+
+* *Namespace introspection* — Ox stores `xmlns` attributes but does not expose
+  namespace accessors on `Ox::Element`. Methods like `node.namespace`,
+  `node.namespaces`, and namespace inheritance are unavailable.
+* *Parent node reparenting* — Ox has no method to change a node's parent after
+  creation, preventing `node.parent=` functionality. Nodes are immutable with
+  respect to their parent relationship.
+
 For complete Ox adapter documentation including all limitations and workarounds,
 see link:docs/_pages/adapters/ox.adoc[Ox Adapter Guide].
 
@@ -912,6 +924,12 @@ comprehensive pure Ruby XPath 1.0 engine.
 * Prefer pure Ruby XPath for debugging
 * Basic namespace queries are sufficient
 
+**Inherited Ox limitations:**
+
+HeadedOx inherits the upstream Ox gem limitations described above (namespace
+introspection and parent node reparenting). Additionally, some sibling axes
+are not fully supported due to Ox's tree structure.
+
 [source,ruby]
 ----
 # Use HeadedOx adapter

data/lib/moxml/adapter/base.rb

@@ -8,9 +8,54 @@ module Moxml
     class Base
       # include XmlUtils
 
+      # Entity marker for adapters that resolve entities during parsing.
+      # U+FFFC (Object Replacement Character) + U+FEFF (BOM) is a two-character
+      # sentinel chosen because this exact sequence followed by a valid entity
+      # name pattern is vanishingly unlikely in real XML content.
+      # Non-standard entities like © are converted to this marker before
+      # parsing, then restored during serialization.
+      # Standard XML entities (& < > " ') are NOT converted.
+      ENTITY_MARKER = "\u{FFFC}\u{FEFF}"
+      ENTITY_NAME_PATTERN = "[a-zA-Z_][\\w.:-]*"
+      ENTITY_NAME_RE = /&(#{ENTITY_NAME_PATTERN});/
+      ENTITY_MARKER_RE = /\u{FFFC}\u{FEFF}(#{ENTITY_NAME_PATTERN});/
+      SERIALIZED_ENTITY_MARKER_RE = /(#{ENTITY_NAME_PATTERN});/
+      STANDARD_ENTITIES = %w[amp lt gt quot apos].freeze
+
       class << self
         include XmlUtils
 
+        # Replace non-standard entity references with markers before parsing.
+        # Always returns a UTF-8 encoded string.
+        def preprocess_entities(xml)
+          return "" if xml.nil?
+
+          str = if xml.encoding == Encoding::BINARY
+                  # Binary strings are assumed to be UTF-8. If the bytes are
+                  # not valid UTF-8, fall back to encoding as UTF-8 with
+                  # replacement to avoid raising on gsub.
+                  dup = xml.dup.force_encoding("UTF-8")
+                  dup.valid_encoding? ? dup : xml.dup.encode("UTF-8", "ASCII-8BIT", invalid: :replace, undef: :replace)
+                elsif xml.encoding == Encoding::UTF_8
+                  xml
+                else
+                  xml.encode("UTF-8")
+                end
+          str.gsub(ENTITY_NAME_RE) do |match|
+            STANDARD_ENTITIES.include?(::Regexp.last_match(1)) ? match : "#{ENTITY_MARKER}#{::Regexp.last_match(1)};"
+          end
+        end
+
+        # Restore entity markers back to named entity references.
+        def restore_entities(text)
+          return text unless text.is_a?(String)
+
+          # Force UTF-8 encoding since markers are UTF-8 characters
+          str = text.encoding == Encoding::UTF_8 ? text : text.dup.force_encoding("UTF-8")
+          result = str.gsub(ENTITY_MARKER_RE, '&\1;')
+          result.gsub(SERIALIZED_ENTITY_MARKER_RE, '&\1;')
+        end
+
         def set_root(_doc, _element)
           raise Moxml::NotImplementedError.new(
             "set_root not implemented",
@@ -163,6 +208,26 @@ namespace_validation_mode: :strict)
           child_native
         end
 
+        # Returns all namespaces in scope for this element, including
+        # inherited from ancestors. Adapters with native support (Nokogiri)
+        # override this. Default walks the ancestor chain.
+        def in_scope_namespaces(element)
+          namespaces = {}
+          node = element
+
+          while node
+            break unless node_type(node) == :element
+
+            namespace_definitions(node).each do |ns|
+              prefix = namespace_prefix(ns)
+              namespaces[prefix] = ns unless namespaces.key?(prefix)
+            end
+            node = parent(node)
+          end
+
+          namespaces.values
+        end
+
         protected
 
         def create_native_element(_name, _owner_doc = nil)
@@ -236,14 +301,6 @@ namespace_validation_mode: :strict)
             adapter: name,
           )
         end
-
-        def in_scope_namespaces(_element)
-          raise Moxml::NotImplementedError.new(
-            "in_scope_namespaces not implemented",
-            feature: "in_scope_namespaces",
-            adapter: name,
-          )
-        end
       end
     end
   end

data/lib/moxml/adapter/headed_ox.rb

@@ -30,8 +30,9 @@ module Moxml
         # ~176K allocations per 100-element parse). Lazy parse defers wrapper
         # creation until nodes are accessed, matching Ox adapter behavior.
         def parse(xml, options = {}, _context = nil)
+          processed_xml = preprocess_entities(xml)
           native_doc = begin
-            result = ::Ox.parse(xml)
+            result = ::Ox.parse(processed_xml)
 
             # result can be either Document or Element
             if result.is_a?(::Ox::Document)

data/lib/moxml/adapter/libxml.rb

@@ -56,6 +56,11 @@ module Moxml
                          xml.to_s
                        end
 
+          # Preprocess entities before parsing.
+          # This converts the string to UTF-8; LibXML will use the encoding
+          # parameter or XML declaration for byte interpretation.
+          xml_string = preprocess_entities(xml_string)
+
           # Extract DOCTYPE before parsing
           doctype_match = xml_string.match(/<!DOCTYPE\s+(\S+)(?:\s+PUBLIC\s+"([^"]+)"\s+"([^"]+)"|  \s+SYSTEM\s+"([^"]+)")?\s*>/i)
 
@@ -842,9 +847,17 @@ module Moxml
           return [] unless native_node
           return [] unless native_node.is_a?(::LibXML::XML::Node)
 
-          native_node.namespaces.map do |ns|
-            ns
-          end
+          namespaces = native_node.namespaces
+          return [] unless namespaces
+
+          namespace_list =
+            if namespaces.respond_to?(:definitions)
+              namespaces.definitions
+            else
+              namespaces
+            end
+
+          namespace_list.to_a
         end
 
         # Doctype accessor methods

data/lib/moxml/adapter/nokogiri.rb

@@ -16,14 +16,18 @@ module Moxml
         end
 
         def parse(xml, options = {}, _context = nil)
+          processed_xml = preprocess_entities(xml)
+
+          # preprocess_entities always returns UTF-8, so tell Nokogiri to
+          # parse as UTF-8 regardless of any original encoding option.
           native_doc = begin
             if options[:fragment]
-              ::Nokogiri::XML::DocumentFragment.parse(xml) do |config|
+              ::Nokogiri::XML::DocumentFragment.parse(processed_xml) do |config|
                 config.strict.nonet
                 config.recover unless options[:strict]
               end
             else
-              ::Nokogiri::XML(xml, nil, options[:encoding]) do |config|
+              ::Nokogiri::XML(processed_xml, nil, "UTF-8") do |config|
                 config.strict.nonet
                 config.recover unless options[:strict]
               end
@@ -180,10 +184,16 @@ module Moxml
         def children(node)
           node.children.reject do |child|
             child.text? && child.content.strip.empty? &&
-              !(child.previous_sibling.nil? && child.next_sibling.nil?)
+              !(child.previous_sibling.nil? && child.next_sibling.nil?) &&
+              !adjacent_to_entity_reference?(child)
           end
         end
 
+        def adjacent_to_entity_reference?(node)
+          node.previous_sibling.is_a?(::Nokogiri::XML::EntityReference) ||
+            node.next_sibling.is_a?(::Nokogiri::XML::EntityReference)
+        end
+
         def replace_children(node, new_children)
           node.children.unlink
           new_children.each { |child| add_child(node, child) }
@@ -288,7 +298,7 @@ module Moxml
         end
 
         def text_content(node)
-          node.text
+          node.text.to_s
         end
 
         def inner_text(node)