moxml 0.1.26 → 0.3.0

data/lib/moxml/entity/reference.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module Moxml
+  module Entity
+    # A named entity reference (&name;) as a value object, for
+    # adapters whose native trees cannot represent entity references
+    # (ox stores them in the tree; rexml and leptris carry them
+    # alongside). Adapter-specific namespaces alias this class so
+    # node_type dispatch keeps working.
+    class Reference
+      attr_reader :name
+      attr_accessor :parent
+
+      def initialize(name)
+        @name = name
+        @parent = nil
+      end
+
+      def to_xml
+        "&#{name};"
+      end
+
+      def ==(other)
+        other.is_a?(Reference) && name == other.name
+      end
+    end
+  end
+end

data/lib/moxml/entity/restorer.rb

@@ -0,0 +1,95 @@
+# frozen_string_literal: true
+
+module Moxml
+  module Entity
+    # Restores configured character entities into explicit
+    # Moxml::Entity::Reference nodes after a native tree has been
+    # parsed and wrapped — for adapters whose parser resolves entities
+    # during parsing (libxml, and the restore_entities option on
+    # rexml/oga).
+    class Restorer
+      def initialize(doc)
+        @doc = doc
+        @ctx = doc.context
+        @registry = @ctx.entity_registry
+        @config = @ctx.config
+        @adapter = @ctx.config.adapter
+      end
+
+      def run
+        return unless @registry && @doc.root
+
+        walk(@doc.root)
+      end
+
+      private
+
+      def walk(element)
+        # Snapshot because we may add/remove siblings during the walk.
+        element.children.to_a.each do |child|
+          if child.is_a?(::Moxml::Text)
+            restore_text_node(child)
+          elsif child.is_a?(::Moxml::Element)
+            walk(child)
+          end
+        end
+      end
+
+      # Includes the adapter limitation that adjacent native text
+      # nodes get merged.
+      def restore_text_node(text_node)
+        content = text_node.content
+        return unless content
+
+        chunks = chunk_text(content)
+        return if chunks.size == 1 && chunks.first.first == :text
+
+        parent = text_node.parent
+        return unless parent
+
+        text_node.remove
+        chunks.each { |type, payload| append_chunk(parent, type, payload) }
+      end
+
+      def chunk_text(content)
+        chunks = []
+        buffer = +""
+        restorable = @registry.restorable_codepoints
+
+        content.each_char do |char|
+          cp = char.ord
+          if restorable.include?(cp) &&
+              (name = @registry.primary_name_for_codepoint(cp)) &&
+              @registry.should_restore?(cp, config: @config)
+            unless buffer.empty?
+              chunks << [:text, buffer.dup]
+              buffer.clear
+            end
+            chunks << [:eref, name]
+          else
+            buffer << char
+          end
+        end
+
+        chunks << [:text, buffer.dup] unless buffer.empty?
+        chunks
+      end
+
+      def append_chunk(parent, type, payload)
+        case type
+        when :text
+          parent.add_child(::Moxml::Text.new(
+                             @adapter.create_native_text(payload), @ctx
+                           ))
+        when :eref
+          parent.add_child(
+            ::Moxml::EntityReference.new(
+              @adapter.create_native_entity_reference(payload),
+              @ctx,
+            ),
+          )
+        end
+      end
+    end
+  end
+end

data/lib/moxml/entity.rb

@@ -0,0 +1,126 @@
+# frozen_string_literal: true
+
+module Moxml
+  # Entity-reference round-trip pipeline.
+  #
+  # XML libraries split into two camps: those that preserve named
+  # entity references natively (nokogiri) and those that expand or
+  # reject them at parse (ox, rexml, oga, libxml, leptris). Moxml
+  # bridges the camps with one pipeline, owned here and delegated to
+  # by Adapter::Base:
+  #
+  # 1. Parse time — .preprocess_entities rewrites non-standard
+  #    entity references to a two-character marker (see MARKER) so
+  #    the reference survives native parsing verbatim. The five
+  #    standard entities (& < > " ') are NOT
+  #    converted.
+  # 2. Read time — marker-bearing text is split into text and
+  #    Entity::Reference nodes (adapters whose natives cannot hold
+  #    references), or decoded in place (.decode_entities covers the
+  #    five standard entities plus numeric character references).
+  # 3. Serialize time — .restore_entities maps markers back to named
+  #    references, including markers a native serializer already
+  #    rendered as character references.
+  #
+  # How references are STORED between parse and serialize is
+  # adapter-shaped (in-tree value objects for ox, attachment
+  # sequences for rexml/libxml, text markers for oga/leptris); the
+  # marker lifecycle and the Entity::Reference value type are the
+  # shared, single-sourced parts.
+  module Entity
+    autoload :Reference, "moxml/entity/reference"
+    autoload :Restorer, "moxml/entity/restorer"
+
+    # 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.
+    MARKER = "\u{FFFC}\u{FEFF}"
+    NAME_PATTERN = "[a-zA-Z_][\\w.:-]*"
+    NAME_RE = /&(#{NAME_PATTERN});/
+    MARKER_RE = /\u{FFFC}\u{FEFF}(#{NAME_PATTERN});/
+    SERIALIZED_MARKER_RE = /(#{NAME_PATTERN});/
+    STANDARD_ENTITIES = %w[amp lt gt quot apos].freeze
+
+    NAMED_DECODE_MAP = {
+      "amp" => "&", "lt" => "<", "gt" => ">",
+      "quot" => '"', "apos" => "'"
+    }.freeze
+    private_constant :NAMED_DECODE_MAP
+
+    DECODE_RE = /&(?:(amp|lt|gt|quot|apos)|#(?:(\d+)|[xX]([0-9a-fA-F]+)));/
+    private_constant :DECODE_RE
+
+    module_function
+
+    # 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")
+              if dup.valid_encoding?
+                dup
+              else
+                xml.dup.encode("UTF-8",
+                               "ASCII-8BIT", invalid: :replace, undef: :replace)
+              end
+            elsif xml.encoding == Encoding::UTF_8
+              xml
+            else
+              xml.encode("UTF-8")
+            end
+      # Fast path: no `&` means no entity references to mark — skip
+      # the regex scan and string allocation entirely. The vast
+      # majority of XML payloads contain no entity references.
+      return str unless str.include?("&")
+
+      str.gsub(NAME_RE) do |match|
+        STANDARD_ENTITIES.include?(::Regexp.last_match(1)) ? match : "#{MARKER}#{::Regexp.last_match(1)};"
+      end
+    end
+
+    # Resolve numeric (&#NN; / &#xNN;) and the five standard named
+    # (&amp; &lt; &gt; &quot; &apos;) XML entity references in one
+    # single pass. The resulting characters are data; no further
+    # decoding is applied. Numeric refs producing invalid UTF-8
+    # (NUL, surrogate halves, > U+10FFFF) are preserved verbatim
+    # to avoid silently emitting malformed bytes.
+    def decode_entities(text)
+      return text unless text.is_a?(String) && text.include?("&")
+
+      text.gsub(DECODE_RE) do
+        if (named = ::Regexp.last_match(1))
+          NAMED_DECODE_MAP[named]
+        else
+          code = ::Regexp.last_match(2) ? ::Regexp.last_match(2).to_i : ::Regexp.last_match(3).to_i(16)
+          if code.zero? || code.between?(0xD800, 0xDFFF) || code > 0x10FFFF
+            ::Regexp.last_match(0)
+          else
+            [code].pack("U")
+          end
+        end
+      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")
+      # Fast path: the vast majority of documents carry no entity
+      # markers — two C-level scans beat two regex passes.
+      return str unless str.include?(MARKER) ||
+        str.include?("&#xFFFC;")
+
+      result = str.gsub(MARKER_RE, '&\1;')
+      result.gsub(SERIALIZED_MARKER_RE, '&\1;')
+    end
+  end
+end

data/lib/moxml/entity_registry.rb

@@ -199,7 +199,7 @@ module Moxml
     end
 
     # Returns the set of codepoints that could potentially be restored as entities.
-    # Used by DocumentBuilder for O(1) fast-path checks.
+    # Used by Entity::Restorer for O(1) fast-path checks.
     # @return [Set<Integer>]
     def restorable_codepoints
       @restorable_codepoints ||= if @by_name.empty?

data/lib/moxml/error.rb

@@ -106,27 +106,6 @@ module Moxml
     end
   end
 
-  # Error raised when serialization fails
-  class SerializationError < Error
-    attr_reader :node, :adapter, :format
-
-    def initialize(message, node: nil, adapter: nil, format: nil)
-      @node = node
-      @adapter = adapter
-      @format = format
-      super(message)
-    end
-
-    def to_s
-      msg = super
-      msg += "\n  Node: <#{@node.name}>" if @node.is_a?(Element) || @node.is_a?(Attribute)
-      msg += "\n  Adapter: #{@adapter}" if @adapter
-      msg += "\n  Format: #{@format}" if @format
-      msg += "\n  Hint: Check that the node structure is valid for serialization"
-      msg
-    end
-  end
-
   # Error raised when document structure is invalid
   class DocumentStructureError < Error
     attr_reader :attempted_operation, :current_state
@@ -146,27 +125,6 @@ module Moxml
     end
   end
 
-  # Error raised when attribute operations fail
-  class AttributeError < Error
-    attr_reader :attribute_name, :element, :value
-
-    def initialize(message, name: nil, element: nil, value: nil)
-      @attribute_name = name
-      @element = element
-      @value = value
-      super(message)
-    end
-
-    def to_s
-      msg = super
-      msg += "\n  Attribute: #{@attribute_name}" if @attribute_name
-      msg += "\n  Element: <#{@element.name}>" if @element.is_a?(Element)
-      msg += "\n  Value: #{@value.inspect}" if @value
-      msg += "\n  Hint: Verify attribute name follows XML naming rules"
-      msg
-    end
-  end
-
   # Error raised when a feature is not implemented by an adapter
   class NotImplementedError < Error
     attr_reader :feature, :adapter

data/lib/moxml/node.rb

@@ -21,7 +21,12 @@ module Moxml
     # Update native reference after identity-changing operations
     # (e.g., LibXML doc.root= creates a new Ruby wrapper)
     def refresh_native!(new_native)
-      @native = new_native
+      unless new_native.equal?(@native)
+        context.unregister_wrapper(@native)
+        @native = new_native
+        context.register_wrapper(new_native, self)
+      end
+      self
     end
 
     def document
@@ -55,6 +60,8 @@ module Moxml
       refreshed = adapter.actual_native(node.native, @native)
       node.refresh_native!(refreshed) if refreshed && refreshed != node.native
       node.parent_node = self
+      # The adopted subtree's in-scope namespaces changed
+      node.invalidate_namespace_cache!
       invalidate_children_cache!
       self
     end
@@ -77,9 +84,15 @@ module Moxml
       invalidate_parent_children_cache!
       adapter.remove(@native)
       invalidate_children_cache!
+      # The detached subtree left its declaring ancestors behind
+      invalidate_namespace_cache!
       self
     end
 
+    # Namespace-scope caches live on Element; the base no-op lets tree
+    # mutations invalidate uniformly without type checks.
+    def invalidate_namespace_cache!; end
+
     def replace(node)
       node = prepare_node(node)
       invalidate_parent_children_cache!
@@ -103,7 +116,10 @@ module Moxml
     end
 
     def xpath(expression, namespaces = {})
-      NodeSet.new(adapter.xpath(@native, expression, namespaces), context)
+      result = adapter.xpath(@native, expression, namespaces)
+      # Adapter contract: Array<native> | scalar. Scalars (count(),
+      # string-length(), booleans) pass through unwrapped.
+      result.is_a?(Array) ? NodeSet.new(result, context) : result
     end
 
     def at_xpath(expression, namespaces = {})
@@ -186,6 +202,104 @@ module Moxml
       children.each(&block)
     end
 
+    # Returns all ancestor nodes from the parent up to and including
+    # the document node.
+    #
+    # @return [NodeSet] ancestors ordered nearest-first
+    def ancestors
+      return NodeSet.new([], context) if document?
+
+      natives = []
+      current = parent
+      while current
+        natives << current.native
+        break if current.document?
+
+        current = current.parent
+      end
+      NodeSet.new(natives, context)
+    end
+
+    # Returns all descendant nodes (children, grandchildren, and so on),
+    # excluding the node itself.
+    #
+    # @return [NodeSet] descendants in document order
+    def descendants
+      natives = []
+      each_node { |node| natives << node.native }
+      NodeSet.new(natives, context)
+    end
+
+    # Returns the siblings after this node, in document order.
+    #
+    # @return [NodeSet]
+    def following_siblings
+      parent = self.parent
+      return NodeSet.new([], context) unless parent
+
+      siblings = parent.children.to_a
+      index = siblings.index { |child| child.native.equal?(@native) }
+      return NodeSet.new([], context) if index.nil?
+
+      NodeSet.new(siblings[(index + 1)..].map(&:native), context)
+    end
+
+    # Returns the siblings before this node, in document order.
+    #
+    # @return [NodeSet]
+    def preceding_siblings
+      parent = self.parent
+      return NodeSet.new([], context) unless parent
+
+      siblings = parent.children.to_a
+      index = siblings.index { |child| child.native.equal?(@native) }
+      return NodeSet.new([], context) if index.nil?
+
+      NodeSet.new(siblings[0...index].map(&:native), context)
+    end
+
+    # Deep copy of the node (both dup and clone create deep copies for XML nodes)
+    def dup
+      Moxml::Node.wrap(adapter.duplicate_node(@native), context)
+    end
+
+    alias clone dup
+
+    # Returns an XPath expression that uniquely locates this node within
+    # its document. Positional predicates are emitted only when sibling
+    # elements share the same qualified name, keeping paths minimal.
+    #
+    # @return [String] XPath expression
+    # @raise [Moxml::NotImplementedError] for node types other than
+    #   element and document
+    def path
+      return "/" if document?
+
+      unless element?
+        raise Moxml::NotImplementedError.new(
+          "path is only supported for element and document nodes",
+          feature: "path",
+        )
+      end
+
+      segments = []
+      current = self
+      while current && !current.document?
+        segments.unshift(path_segment_for(current))
+        current = current.parent
+      end
+      "/#{segments.join('/')}"
+    end
+
+    # Returns the 1-based line number where this node appears in the
+    # source XML, or nil when the underlying adapter does not track
+    # source positions.
+    #
+    # @return [Integer, nil]
+    def line_number
+      adapter.line_number(@native)
+    end
+
     def outer_xml
       to_xml
     end
@@ -202,13 +316,6 @@ module Moxml
       text.strip.empty?
     end
 
-    # Deep copy of the node (both dup and clone create deep copies for XML nodes)
-    def dup
-      Moxml::Node.wrap(adapter.dup(@native), context)
-    end
-
-    alias clone dup
-
     def ==(other)
       self.class == other.class && @native == other.native
     end
@@ -251,10 +358,13 @@ module Moxml
     def self.wrap(node, context)
       return nil if node.nil?
 
+      cached = context.wrapper_for(node)
+      return cached if cached
+
       type = adapter(context).node_type(node)
       klass = node_type_map[type] || self
 
-      klass.new(node, context)
+      klass.new(node, context).tap { |wrapper| context.register_wrapper(node, wrapper) }
     end
 
     # Internal: Set the parent node for cache invalidation tracking.
@@ -286,6 +396,21 @@ module Moxml
 
     private
 
+    # XPath segment for an element: the qualified name, plus a positional
+    # predicate only when same-named element siblings make it ambiguous.
+    def path_segment_for(element)
+      name = element.name
+      parent = element.parent
+      return name unless parent
+
+      same_name = parent.children.select do |child|
+        child.element? && child.name == name
+      end
+      return name if same_name.size == 1
+
+      "#{name}[#{same_name.find_index(element) + 1}]"
+    end
+
     def prepare_node(node)
       case node
       when String then Text.new(adapter.create_text(node), context)

data/lib/moxml/node_set.rb

@@ -64,7 +64,7 @@ module Moxml
     end
 
     def +(other)
-      self.class.new(@nodes + other.nodes, @context)
+      self.class.new(@nodes + other.nodes, @context, @parent_node)
     end
 
     def <<(node)

data/lib/moxml/sax/namespace_splitter.rb

@@ -9,6 +9,8 @@ module Moxml
     # attribute. This module provides a single implementation.
     module NamespaceSplitter
       # @param attributes [Hash, Array<Array>] attributes as a hash or array of pairs
+      # @yieldparam value [Object] raw attribute/namespace value
+      # @yieldreturn [Object] transformed value to store
       # @return [Array(Hash, Hash)] [regular_attrs, namespaces]
       def split_attributes_and_namespaces(attributes)
         attrs = {}
@@ -16,11 +18,12 @@ module Moxml
 
         each_attribute(attributes) do |name, value|
           name_s = name.to_s
+          v = block_given? ? yield(value) : value
           if name_s == "xmlns" || name_s.start_with?("xmlns:")
             prefix = name_s == "xmlns" ? nil : name_s.sub("xmlns:", "")
-            ns[prefix] = value
+            ns[prefix] = v
           else
-            attrs[name_s] = value
+            attrs[name_s] = v
           end
         end
 

data/lib/moxml/signature/model/key/dsa_key_value.rb

@@ -10,7 +10,7 @@ module Moxml
         class DSAKeyValue
           attr_accessor :p, :q, :g, :y, :j, :seed, :pgen_counter
 
-          # rubocop:disable Naming/MethodParameterName -- P/Q/G/Y/J are W3C spec names
+          # rubocop:disable-next Naming/MethodParameterName -- P/Q/G/Y/J are W3C spec names
           def initialize(p:, q:, y:, g: nil, j: nil, seed: nil,
                          pgen_counter: nil)
             @p = p
@@ -21,7 +21,6 @@ module Moxml
             @seed = seed
             @pgen_counter = pgen_counter
           end
-          # rubocop:enable Naming/MethodParameterName
         end
       end
     end

data/lib/moxml/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Moxml
-  VERSION = "0.1.26"
+  VERSION = "0.3.0"
 end

data/lib/moxml/xml_emitter.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module Moxml
+  # Single source of XML emission knowledge: character escaping,
+  # CDATA end-sequence segmentation, and declaration/DOCTYPE
+  # rendering. Adapters keep their tree walks (those are
+  # adapter-shaped) but stop re-deriving the wire format:
+  #
+  # - text escapes & < >; attribute values also escape " —
+  #   apostrophes stay literal (moxml-canonical form)
+  # - a CDATA section's end sequence is split into adjacent sections
+  # - the moxml declaration shape is <?xml version="..."
+  #   encoding="..." standalone="..."?> with only the set attributes
+  # - DOCTYPE renders PUBLIC and SYSTEM external identifiers
+  module XmlEmitter
+    TEXT_ESCAPE_RE = /[<>&]/
+    TEXT_ESCAPE_MAP = {
+      "<" => "&lt;", ">" => "&gt;", "&" => "&amp;"
+    }.freeze
+    ATTRIBUTE_ESCAPE_RE = /[<>&"]/
+    ATTRIBUTE_ESCAPE_MAP = {
+      "<" => "&lt;", ">" => "&gt;", "&" => "&amp;", '"' => "&quot;"
+    }.freeze
+    CDATA_END = "]]>"
+    CDATA_END_SPLIT = "]]]]><![CDATA[>"
+
+    module_function
+
+    # @return [String] text with & < > escaped
+    def escape_text(text)
+      str = text.is_a?(String) ? text : text.to_s
+      return str unless str.match?(TEXT_ESCAPE_RE)
+
+      str.gsub(TEXT_ESCAPE_RE, TEXT_ESCAPE_MAP)
+    end
+
+    # @return [String] attribute value with & < > " escaped
+    def escape_attribute(value)
+      str = value.is_a?(String) ? value : value.to_s
+      return str unless str.match?(ATTRIBUTE_ESCAPE_RE)
+
+      str.gsub(ATTRIBUTE_ESCAPE_RE, ATTRIBUTE_ESCAPE_MAP)
+    end
+
+    # @return [String] a CDATA section, splitting any embedded end
+    #   sequence into adjacent sections
+    def cdata(content)
+      "<![CDATA[#{content.to_s.gsub(CDATA_END, CDATA_END_SPLIT)}]]>"
+    end
+
+    # @return [String] an XML declaration with only the set attributes
+    def declaration_xml(version, encoding, standalone)
+      output = %(<?xml version="#{version}")
+      output << %( encoding="#{encoding}") if encoding && !encoding.to_s.empty?
+      output << %( standalone="#{standalone}") unless standalone.nil?
+      output << "?>"
+    end
+
+    # @return [String] a DOCTYPE with its external identifier
+    def doctype_xml(name, public_id, system_id)
+      output = "<!DOCTYPE #{name}"
+      if public_id && !public_id.to_s.empty?
+        output << %( PUBLIC "#{public_id}")
+        output << %( "#{system_id}") if system_id
+      elsif system_id && !system_id.to_s.empty?
+        output << %( SYSTEM "#{system_id}")
+      end
+      output << ">"
+    end
+  end
+end