moxml 0.5.148 → 0.5.150

data/lib/moxml/adapter/rexml.rb

@@ -22,6 +22,10 @@ module Moxml
           true
         end
 
+        def element_indent_supported?
+          true
+        end
+
         def parse(xml, options = {}, _context = nil)
           xml = "" if xml.nil?
 
@@ -46,6 +50,29 @@ module Moxml
               )
             end
             create_document
+          rescue ::RuntimeError => e
+            # REXML's entity-expansion cap (and any engine-level
+            # guard) surfaces as a bare RuntimeError; the facade
+            # names it (issue: taxonomy differential, huge-entity
+            # class; the cap itself is D-16).
+            raise Moxml::ParseError.new(
+              e.message,
+              source: xml.is_a?(String) ? xml[0..100] : nil,
+            )
+          end
+
+          # Rootless parses (empty or declaration-only input) are
+          # malformed: XML requires exactly one root. Nokogiri and
+          # leptris raise at the engine; rexml returns a bare
+          # document — the facade names it instead (loudness
+          # differential, TODO.sota/01). Recover mode keeps the
+          # rootless-document fallback with its diagnostics (#147).
+          if options[:strict] && native_doc.respond_to?(:root) &&
+              native_doc.root.nil?
+            raise Moxml::ParseError.new(
+              "document has no root element",
+              source: xml.is_a?(String) ? xml[0..100] : nil,
+            )
           end
 
           ctx = _context || Context.new(:rexml)
@@ -192,8 +219,10 @@ module Moxml
         def children(node, **_entity_bearing)
           return [] unless node.is_a?(::REXML::Parent)
 
-          # Return all children preserving whitespace text nodes
-          result = node.children.dup
+          # Return all children preserving whitespace text nodes. The XML
+          # declaration is document state, not a child node (model,
+          # Object model), so it is never listed.
+          result = node.children.grep_v(::REXML::XMLDecl)
 
           # Include any EntityReference wrappers stored alongside native
           # children. Native children are identity-unique; only this
@@ -435,7 +464,7 @@ module Moxml
         end
 
         def processing_instruction_content(node)
-          node.content
+          node.content.to_s
         end
 
         def set_processing_instruction_content(node, content)
@@ -458,17 +487,26 @@ module Moxml
           return "" unless element
 
           text = ""
-          element.children.each do |child|
-            case child
-            when ::REXML::Text
-              # Preserve original spacing from text nodes exactly including newlines and all whitespace
-              text += child.value
-            when ::REXML::Element
-              # Extract text recursively from child element
-              child_text = extract_text_recursively(child)
-              # Concatenate directly like other adapters - NO SPACE INSERTION
-              text += child_text
+          begin
+            element.children.each do |child|
+              case child
+              when ::REXML::Text
+                # Preserve original spacing from text nodes exactly including newlines and all whitespace
+                text += child.value
+              when ::REXML::Element
+                # Extract text recursively from child element
+                child_text = extract_text_recursively(child)
+                # Concatenate directly like other adapters - NO SPACE INSERTION
+                text += child_text
+              end
             end
+          rescue ::RuntimeError => e
+            # rexml expands entities lazily: the parse accepts, the
+            # read hits the expansion guard (D-16). The facade names
+            # it instead of leaking the bare RuntimeError.
+            raise Moxml::Error,
+                  "entity expansion limit exceeded (rexml guard, D-16): " \
+                  "#{e.message}"
           end
           # Don't strip - preserve original spacing including newlines
           text
@@ -604,6 +642,15 @@ module Moxml
         end
 
         def xpath(node, expression, namespaces = {})
+          # REXML's engine answers no text nodes for text() node
+          # tests (D-07, both axes); the reference engine does
+          # (model, XPath evaluation).
+          if expression.match?(/\btext\s*\(/)
+            return Moxml::XPath.evaluate_natives(
+              node, expression, namespaces || {}, adapter: :rexml
+            )
+          end
+
           # XPath.match for every expression: get_elements only
           # handles simple child-name paths — attribute terminals,
           # absolute paths and predicates silently degrade there.
@@ -612,11 +659,29 @@ module Moxml
           # namespaced elements never match (issue #395).
           namespaces = namespaces.transform_keys(&:to_s) if
             namespaces.is_a?(Hash)
-          if namespaces && !namespaces.empty?
-            ::REXML::XPath.match(node, expression, namespaces).to_a
-          else
-            ::REXML::XPath.match(node, expression).to_a
+          results = if namespaces && !namespaces.empty?
+                      ::REXML::XPath.match(node, expression, namespaces).to_a
+                    else
+                      ::REXML::XPath.match(node, expression).to_a
+                    end
+          # REXML answers unions in expression order (//a | //b on
+          # <r><b/><a/></r> answers a,a,b); path results are
+          # document-ordered by the model (TODO.sota/02, M3) —
+          # re-order here, the oga lane's pattern.
+          return results if results.empty?
+
+          # Scalar arm: count()/string()/boolean()/arithmetic answer a
+          # one-element array holding the value; the adapter contract
+          # passes scalars through unwrapped (numbers as Float,
+          # uniform with the other adapters).
+          unless results.first.is_a?(::REXML::Node)
+            value = results.first
+            return value.is_a?(Numeric) ? value.to_f : value
           end
+
+          ctx = Context.new(:rexml)
+          wrapped = results.map { |n| Moxml::Node.wrap(n, ctx) }
+          Moxml::XPath::Ordering.document_order(wrapped).map(&:native)
         rescue ::REXML::ParseException => e
           raise Moxml::XPathError.new(
             e.message,

data/lib/moxml/c14n/data_model.rb

@@ -115,6 +115,14 @@ module Moxml
           seen_root = false
           idx = 0
           document.children.each do |child|
+            # Whitespace between document-level nodes is not part of
+            # the canonical form (C14N §2.1 renders the document
+            # element and the PIs/comments outside it only). rexml
+            # retains such text nodes at parse (D-15); every engine's
+            # form must still exclude them.
+            next if child.is_a?(::Moxml::Text) ||
+              child.is_a?(::Moxml::Cdata)
+
             if child.is_a?(::Moxml::Element)
               next if seen_root
 

data/lib/moxml/c14n/processor.rb

@@ -21,6 +21,11 @@ module Moxml
       def process(root_node)
         output = (+"")
         process_node(root_node, output)
+        # Document-level PI/comment rendering uses a newline as a
+        # SEPARATOR between nodes (and around the root), not as a
+        # leading/trailing pad: the canonical form starts and ends
+        # with the first/last node itself (libxml2 oracle).
+        output.chomp! if root_node.node_type == :root
         output
       end
 
@@ -93,26 +98,30 @@ module Moxml
         return unless with_comments
         return unless node.in_node_set?
 
-        # Comment outside the document element gets a line break before/after
-        # to keep canonical output readable.
-        if parent_element.nil? && output.length.positive?
-          output << "\n"
-        end
+        ensure_separator(output) if parent_element.nil?
         output << "<!--" << node.value << "-->"
         output << "\n" if parent_element.nil?
       end
 
       def process_pi_node(node, output, parent_element)
         return unless node.in_node_set?
+        # C14N never emits the XML declaration; the "xml" target is
+        # reserved and cannot appear as a PI in a well-formed document.
+        return if node.target.to_s.casecmp("xml").zero?
 
-        if parent_element.nil? && output.length.positive?
-          output << "\n"
-        end
+        ensure_separator(output) if parent_element.nil?
         output << "<?" << node.target
         output << " " << node.data unless node.data.to_s.empty?
         output << "?>"
         output << "\n" if parent_element.nil?
       end
+
+      # One newline between document-level nodes, never a doubled
+      # separator (a PI's trailing newline already starts the next
+      # node's line).
+      def ensure_separator(output)
+        output << "\n" if output.length.positive? && !output.end_with?("\n")
+      end
     end
   end
 end

data/lib/moxml/context.rb

@@ -119,7 +119,11 @@ module Moxml
                    end
       # Allocation-free declaration sniff: String#strip would copy the
       # whole buffer just to test its prefix.
-      has_declaration = xml_string.match?(/\A[ \t\r\n\f\v\0]*<\?xml/)
+      # Invalid byte sequences would raise from the regex before any
+      # adapter sees them; the adapters' named parse errors own
+      # malformed input (taxonomy differential, malformed class).
+      has_declaration = xml_string.valid_encoding? &&
+        xml_string.match?(/\A[ \t\r\n\f\v\0]*<\?xml/)
 
       # Parse with adapter, passing self (context) so adapter can use our config
       parsed_options = default_options.merge(options)
@@ -194,6 +198,19 @@ module Moxml
       Moxml::XSD::Schema.new(handle, self)
     end
 
+    # Compile a RELAX NG schema from source or from a file path (the
+    # engine resolves relative includes against the file's directory).
+    # Adapters without an RNG engine raise Moxml::NotImplementedError.
+    def relaxng(schema_source)
+      handle = config.adapter.relaxng_compile(schema_source.to_s)
+      Moxml::RelaxNG::Schema.new(handle, self)
+    end
+
+    def relaxng_file(path)
+      handle = config.adapter.relaxng_compile_file(path.to_s)
+      Moxml::RelaxNG::Schema.new(handle, self)
+    end
+
     def xslt(stylesheet)
       source = case stylesheet
                when Moxml::Document then stylesheet.to_xml
@@ -278,6 +295,21 @@ module Moxml
         raise ArgumentError, "Handler must inherit from Moxml::SAX::Handler"
       end
 
+      # Loud degradation: an engine that cannot report an event family
+      # raises the named error when the handler subscribes, rather than
+      # answering a silently incomplete stream (model, SAX).
+      SAX::Handler::EVENT_METHODS.each_key do |family|
+        next unless handler.handles?(family)
+        next if config.adapter.sax_event_family_supported?(family)
+
+        raise Moxml::NotImplementedError.new(
+          "SAX #{family} events are not supported by the " \
+          "#{config.adapter.name.split('::').last} adapter",
+          feature: "sax_#{family}",
+          adapter: config.adapter.name,
+        )
+      end
+
       # Delegate to adapter
       config.adapter.sax_parse(xml, handler)
     end

data/lib/moxml/document.rb

@@ -272,7 +272,7 @@ module Moxml
       # - NodeSet: already wrapped, return directly
       # - Array / LazyNodeSet: wrap in NodeSet
       case result
-      when NodeSet, Float, String, TrueClass, FalseClass, NilClass
+      when NodeSet, Numeric, String, TrueClass, FalseClass, NilClass
         result
       when Array, LazyNodeSet
         NodeSet.new(result, context)
@@ -282,12 +282,26 @@ module Moxml
       end
     end
 
+    # The first node of a node-set; scalar results (count(), string(),
+    # boolean()) pass through unwrapped and uniform across adapters.
+    # Adapters whose at_xpath lane falls back to the reference engine
+    # when the native answer is empty (leptris, whose node-set index
+    # is stale after sibling insertion) use it.
     def at_xpath(expression, namespaces = nil)
-      expression = lax_document_path(expression) if relative_name_test?(expression)
+      if adapter.native_at_xpath?
+        expression = lax_document_path(expression) if relative_name_test?(expression)
+        result = adapter.at_xpath(@native, expression, namespaces)
+        return result if scalar_result?(result)
 
-      if (native_node = adapter.at_xpath(@native, expression, namespaces))
-        Moxml::Node.wrap(native_node, context)
+        return Moxml::Node.wrap(result, context)
       end
+      result = xpath(expression, namespaces)
+      result.is_a?(NodeSet) ? result.first : result
+    end
+
+    def scalar_result?(result)
+      result.is_a?(Numeric) || result.is_a?(String) ||
+        result == true || result == false || result.nil?
     end
 
     # Quick element creation and addition

data/lib/moxml/node.rb

@@ -36,6 +36,11 @@ module Moxml
       self
     end
 
+    # Document-derived wrapper state (the entity-marker verdict) flows
+    # parent -> child during prewrapped traversal; adapters that keep
+    # no per-wrapper document state carry nothing.
+    def inherit_document_state(_parent); end
+
     def refresh_native!(new_native)
       unless new_native.equal?(@native)
         # Cache-stable binding nodes carry the wrapper in an ivar
@@ -226,7 +231,8 @@ module Moxml
     def attach_previous_sibling(node)
       context.bump_children_generation
       node = prepare_node(node)
-      adapter.add_previous_sibling(@native, node.native)
+      inserted = adapter.add_previous_sibling(@native, node.native)
+      refresh_inserted_native(node, inserted)
       # Invalidate the parent's memoized children list. The wrapper-side
       # @parent_node link is only set when this node was yielded through a
       # parent-aware NodeSet; nodes obtained via at()/xpath() carry no such
@@ -239,12 +245,20 @@ module Moxml
     def attach_next_sibling_to(anchor, node)
       context.bump_children_generation
       node = prepare_node(node)
-      adapter.add_next_sibling(anchor.native, node.native)
+      inserted = adapter.add_next_sibling(anchor.native, node.native)
+      refresh_inserted_native(node, inserted)
       anchor.parent&.invalidate_children_cache!
       anchor.invalidate_parent_children_cache!
       self
     end
 
+    def refresh_inserted_native(node, inserted)
+      return unless adapter.add_sibling_returns_inserted?
+      return if inserted.nil? || inserted.equal?(node.native)
+
+      node.refresh_native!(inserted)
+    end
+
     def remove
       # Nokogiri parity: unlinking an already-detached node is a
       # no-op returning self. Re-attach idioms like
@@ -296,6 +310,21 @@ module Moxml
     end
 
     def to_xml(options = {})
+      # Element-level indentation is a declared capability: engines
+      # that ignore it must not answer unindented output silently
+      # (D-09). indent: 0 and the no-option path stay common.
+      indent = options[:indent]
+      if !is_a?(Document) && indent.is_a?(Integer) && indent.positive? &&
+          !adapter.element_indent_supported?
+        raise Moxml::AdapterError.new(
+          "element-level indentation is not supported by the " \
+          "#{adapter.name.split('::').last} adapter; serialize the " \
+          "document or use indent: 0",
+          adapter: adapter.name,
+          operation: "serialize",
+        )
+      end
+
       # Determine if we should include XML declaration
       # For Document nodes: check native then wrapper, unless explicitly overridden
       # For other nodes: default to no declaration unless explicitly set
@@ -367,9 +396,24 @@ module Moxml
       Materializer.materialize_fields(self, &block)
     end
 
+    # The first node of a node-set; scalar results (count(), string(),
+    # boolean()) pass through unwrapped and uniform across adapters.
+    # Adapters with a native first-only face use it (see
+    # Document#at_xpath).
     def at_xpath(expression, namespaces = {})
-      Moxml::Node.wrap(adapter.at_xpath(@native, expression, namespaces),
-                       context)
+      if adapter.native_at_xpath?
+        result = adapter.at_xpath(@native, expression, namespaces)
+        return result if scalar_result?(result)
+
+        return Moxml::Node.wrap(result, context)
+      end
+      result = xpath(expression, namespaces)
+      result.is_a?(NodeSet) ? result.first : result
+    end
+
+    def scalar_result?(result)
+      result.is_a?(Numeric) || result.is_a?(String) ||
+        result == true || result == false || result.nil?
     end
 
     # Nokogiri-compatible sugar: at/search/at_css/css. Nokogiri's
@@ -410,10 +454,16 @@ module Moxml
     end
 
     # Nokogiri-compatible depth-first traversal: yields self, then
-    # children recursively (document-order visitor).
+    # children recursively (document-order visitor). Document-level
+    # parts (Declaration, Doctype) are state, not nodes: they are
+    # never yielded, and their (adapter-specific, sometimes missing)
+    # child faces are never consulted (issue-free by the model's
+    # object-model rule; found by the taxonomy differential).
     def traverse(&block)
       return to_enum(:traverse) unless block
 
+      return self if is_a?(Moxml::Declaration) || is_a?(Moxml::Doctype)
+
       yield self
       children.each { |child| child.traverse(&block) }
       self
@@ -682,9 +732,16 @@ module Moxml
       end
     end
 
-    # The adapter's type probe is an FFI call per invocation; the
-    # type is fixed for a node's lifetime, so the first answer is
-    # memoized on the wrapper.
+    # The node's kind (the model's Kind face): :document, :element,
+    # :text, :comment, :cdata, :processing_instruction, :doctype,
+    # :declaration, :entity_reference, :namespace, :attribute. The
+    # adapter's type probe is an FFI call per invocation; the type is
+    # fixed for a node's lifetime, so the first answer is memoized on
+    # the wrapper.
+    def node_type
+      node_type_cached
+    end
+
     def node_type_cached
       @node_type_cached ||= adapter.node_type(@native)
     end
@@ -890,6 +947,16 @@ module Moxml
       # input native keeps its registration so later wraps of the
       # same base object hit the cache instead of re-minting.
       if (extended = adapter.wrap_native(node, type, context))
+        # A native that already carries the contract IS the wrapper
+        # (leptris C mint): prime it in place and skip the WeakMap
+        # round trip — the primed @native-identity answers every
+        # later wrap through the fast path above.
+        if extended.equal?(node) && extended.is_a?(Node)
+          extended.prime_contract(extended, context, adapter, type) unless
+            extended.instance_variable_defined?(:@context)
+          return extended
+        end
+
         extended.prime_contract(extended, context, adapter, type)
         context.register_wrapper(node, extended)
         context.register_wrapper(extended, extended) unless extended.equal?(node)

data/lib/moxml/node_set.rb

@@ -39,12 +39,18 @@ module Moxml
     # nodes: Array of natives, or an adapter's LazyNodeSet — the
     # native set is held unmaterialized until an operation needs an
     # Array (#+, #<<, #delete, Range slices).
-    def initialize(nodes, context, parent_node = nil)
+    #
+    # prewrapped: the adapter vouches the entries are already
+    # contract-carrying wrappers (the leptris C-mint children face),
+    # so the walk path skips the wrapped-buffer allocation and the
+    # per-child wrap dispatch.
+    def initialize(nodes, context, parent_node = nil, prewrapped: false)
       @nodes = nodes.is_a?(Array) ? nodes : nil
       @lazy = @nodes ? nil : nodes
       @context = context
       @wrapped = nil
       @parent_node = parent_node
+      @prewrapped = prewrapped
     end
 
     # The raw native nodes — adapter-internal work only (issue #26).
@@ -59,6 +65,13 @@ module Moxml
     def each
       return to_enum(:each) unless block_given?
 
+      if @prewrapped
+        (@nodes || @lazy).each do |node|
+          yield adopt_prewrapped(node)
+        end
+        return self
+      end
+
       wrapped = wrapped_buffer
       index = 0
       (@nodes || @lazy).each do |node|
@@ -119,6 +132,17 @@ module Moxml
 
     # Nokogiri-compatible: Array#flatten and multiple-assignment
     # treat a NodeSet as its wrapped-element array via to_ary.
+    # The same node-set in document order (XPath path results are
+    # conventionally document-ordered; the compiler batches multi-step
+    # evaluation and must re-order). Wrappers are ordered, then the
+    # internal natives are re-paired — no re-wrapping.
+    def document_order
+      return self if native_nodes.size < 2
+
+      ordered = Moxml::XPath::Ordering.document_order(to_a)
+      NodeSet.new(ordered.map(&:native), @context, @parent_node)
+    end
+
     def to_ary
       to_a
     end
@@ -216,5 +240,22 @@ module Moxml
       end
       wrapped
     end
+
+    # The prewrapped entry path: prime a not-yet-primed C-minted
+    # wrapper in place (one ivar check), attach the traversal parent,
+    # and hand the document's marker verdict down the tree.
+    def adopt_prewrapped(node)
+      unless node.is_a?(Moxml::Node)
+        node = Moxml::Node.wrap(node, @context)
+      end
+      unless node.instance_variable_defined?(:@context)
+        node.prime_contract(node, @context, Moxml::Node.adapter(@context))
+      end
+      if @parent_node
+        node.parent_node = @parent_node
+        node.inherit_document_state(@parent_node)
+      end
+      node
+    end
   end
 end

data/lib/moxml/reference/normalizer.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Moxml
+  module Reference
+    # Pure-Ruby normalization faces: XML 1.0 §2.11 line endings and
+    # entity expansion. These are the model's normative answers with
+    # no engine involved; adapters are differentially tested against
+    # them.
+    module Normalizer
+      BUILTIN_ENTITIES = {
+        "amp" => "&", "lt" => "<", "gt" => ">",
+        "quot" => '"', "apos" => "'"
+      }.freeze
+      ENTITY_REFERENCE = /&([^;&<>]*);/
+
+      module_function
+
+      # CRLF → LF; bare CR → LF. Character references are untouched
+      # (&#xD; keeps a literal CR).
+      def normalize_eol(text)
+        text.to_s.gsub("\r\n", "\n").gsub("\r", "\n")
+      end
+
+      # Attribute-value normalization: literal tab/newline/CR become a
+      # space (character references keep their value).
+      def normalize_attribute_literal(text)
+        text.to_s.gsub(/[\t\n\r]/, " ")
+      end
+
+      # Expand built-in and numeric references; custom entities come
+      # from the provided table. An undefined reference raises a named
+      # ParseError (the model has no silently unresolved entities).
+      def expand_entities(text, entities = {})
+        text.to_s.gsub(ENTITY_REFERENCE) do
+          reference = Regexp.last_match(1)
+          resolve(reference, BUILTIN_ENTITIES.merge(entities))
+        end
+      end
+
+      def resolve(reference, entities)
+        if reference.start_with?("#x")
+          numeric(reference[2..], 16)
+        elsif reference.start_with?("#")
+          numeric(reference[1..], 10)
+        elsif BUILTIN_ENTITIES.key?(reference)
+          BUILTIN_ENTITIES[reference]
+        else
+          value = entities[reference]
+          raise ParseError, "undefined entity &#{reference};" unless value
+
+          expand_entities(value, entities)
+        end
+      end
+
+      def numeric(digits, base)
+        pattern = base == 16 ? /\A[0-9A-Fa-f]+\z/ : /\A[0-9]+\z/
+        raise ParseError, "malformed character reference" unless digits.match?(pattern)
+
+        [digits.to_i(base)].pack("U")
+      end
+    end
+  end
+end