moxml 0.5.18 → 0.5.20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c793d84315c4005a5141698aeb716c001d23b7157b768c77cbdb3539a4b08f53
-  data.tar.gz: 35c1d60e6d3a8e17e9768c733d028962bcb6e5798e3c8528b18deaebd855ae5f
+  metadata.gz: 59c8df5982f2b80280386a94385ceed9a65b1b80524772d914e19052a564aedd
+  data.tar.gz: 3e3432a24b65e60bddf345955d4454a5a459f4898693fa9037b71e8a052a6115
 SHA512:
-  metadata.gz: '092b193420e9117adbd6dade8718474c9a72de401eb0b7a741d36639bbd7e9285c7e53d55f96b482b17bea3382d1da3adb1cae6bbc7b787c552859d80377db39'
-  data.tar.gz: 18a342a60a7dda872730dd2a9158aa852948596e21fc4613961d0336ece2f12977d02fe434e7fa64429f3ce73015a4434285f3f052425c4eb6d88c20a9571db7
+  metadata.gz: 3c041e77c6230d320e5a2779f08ffe29505780d4eac520ce1c12c83d5532102153787b592d999067daef2aabfedf08c5a1830d374baa224a9d795e20816faf69
+  data.tar.gz: 54367812683befdea88202d68a7c15c14b91184e3d350cef9510d94a8e6c769d307f311282041d2816626de181697a8f78b429cb7e71ae2b2d11638d34d0a1f9

data/.github/workflows/rake.yml

@@ -53,3 +53,8 @@ jobs:
 
       - name: Run rubocop
         run: bundle exec rubocop
+
+      - name: Run performance gates
+        env:
+          RUN_PERFORMANCE: "1"
+        run: bundle exec rake spec:performance

data/Rakefile

@@ -222,8 +222,9 @@ namespace :spec do
     t.pattern = "spec/examples/**/*_spec.rb"
   end
 
-  desc "Run performance benchmarks"
+  desc "Run performance benchmarks (sets RUN_PERFORMANCE=1)"
   RSpec::Core::RakeTask.new(:performance) do |t|
+    ENV["RUN_PERFORMANCE"] = "1"
     t.pattern = "spec/performance/**/*_spec.rb"
     t.rspec_opts = "--tag performance"
   end
@@ -288,4 +289,4 @@ namespace :opal do
   end
 end
 
-task default: %i[spec rubocop]
+task default: :spec

data/docs/_pages/adapter-protocol.adoc

@@ -59,8 +59,8 @@ Serialization::
 `serialize(node, options)`. Options: `indent`, `encoding`,
 `declaration`, `no_declaration`, `expand_empty`, `line_ending`,
 `indent_text` (the indent-unit string — Nokogiri and
-leptris >= 1.9.45; leptris text-bearing leaves wait on
-leptris/leptris#658).
+leptris >= 1.9.45; its element unit path
+drops comments — leptris-ruby#115).
 Entity-marker restoration is owned by the wrapper layer
 (`Node#to_xml`), guarded by `entity_bearing?`.
 

data/docs/_pages/adapters/leptris.adoc

@@ -31,9 +31,11 @@ ctx.config.adapter_name        # => :leptris / :nokogiri / :rexml (Opal)
 == Parse options
 
 `noblanks: true`::
-Drop whitespace-only text nodes (libxml2 `XML_PARSE_NOBLANKS`
-parity, issue #153) — the parse shape canon's pretty-printer
-compares against `Nokogiri::XML(xml, &:noblanks)`.
+Drop whitespace-only text nodes — libxml2 `XML_PARSE_NOBLANKS`
+semantics (issues #153/#156): boundary spaces of text-bearing
+nodes survive. Implemented moxml-side (the engine flag trims
+boundaries too — leptris/leptris/#677); requires a mutable
+document, so `readonly: true` + `noblanks: true` raises.
 
 `readonly: true`::
 The binding memoizes every read and refuses mutations — the
@@ -68,9 +70,10 @@ implementation over one `leptris_node_traverse` call.
 == Known limitations (tracked upstream)
 
 * Tab indentation honors the indent-unit string on leptris >= 1.9.45
-  (`indent_text:`), byte-identical to Nokogiri on element-only
-  trees; text-bearing leaves still emit spaces until the engine fix
-  (leptris/leptris#658).
+  (`indent_text:`), byte-identical to Nokogiri including
+  text-bearing children since the engine fix (leptris/leptris#658,
+  1.9.46); comment children still diverge on the element unit path
+  (leptris-ruby#115).
 * A PI preceding the DOCTYPE reorders on serialization — libleptris
   normalizes DOCTYPE-first and the document node does not record its
   relative position.

data/lib/moxml/adapter/leptris/document_parts.rb

@@ -76,6 +76,9 @@ module Moxml
         # only walks the root subtree, so declaration, DOCTYPE, PIs and
         # document-level text are assembled around it explicitly.
         def serialize_document(doc, options)
+          fast = fast_document_output(doc, options)
+          return fast if fast
+
           # Nokogiri's document shape: every top-level part is
           # newline-terminated, at any indent — declaration, DOCTYPE,
           # document PIs, the root element, trailing newline after it.
@@ -108,6 +111,69 @@ module Moxml
           parts.join
         end
 
+        # Issue #158: the engine's whole-document serializer is one C
+        # call; the composed path serializes the root through the
+        # element face, which copies the subtree into a fresh document
+        # on every call (~4.5x slower end to end). The engine's output
+        # is byte-identical to the composed one EXCEPT epilog parts
+        # glue directly to the root — so the fast path declines
+        # whenever anything follows the root, any attachment overrides
+        # a part, or the engine's declaration line differs from the
+        # facade's canonical form (checked post-hoc: a source
+        # declaration carrying standalone or another version would
+        # diverge).
+        def fast_document_output(doc, options)
+          return nil unless LIBXML2_LAYOUT_PARITY
+          return nil if attachments.get(doc, :declaration) ||
+            attachments.get(doc, :doctype) ||
+            attachments.get(doc, :document_text) ||
+            attachments.get(doc, :entity_markers)
+
+          include_decl = !options[:no_declaration] && options.fetch(:declaration) do
+            document_has_declaration?(doc)
+          end
+
+          root_seen = false
+          doc.children.each do |child|
+            if child.is_a?(::Leptris::XML::Element)
+              return nil if root_seen
+
+              root_seen = true
+            elsif root_seen
+              # Epilog parts glue directly to the root in the engine's
+              # document output — compose those.
+              return nil
+            end
+          end
+
+          # The engine's subset serializer mangles every declaration
+          # after the first (loses its "<") — moxml's own formatter is
+          # correct, so multi-declaration subsets compose.
+          dt = doc.doctype
+          if dt&.class&.method_defined?(:internal_subset) &&
+              (subset = dt.internal_subset) && subset.scan("<!").size > 1
+            return nil
+          end
+
+          kwargs = {
+            indent: options.fetch(:indent, 0),
+            no_decl: !include_decl,
+            encoding: options[:encoding],
+          }
+          if INDENT_UNIT_SUPPORTED && options[:indent_text].is_a?(String)
+            kwargs[:indent_text] = options[:indent_text]
+          end
+          output = doc.to_xml(**kwargs)
+          return nil if output.nil? || output.empty?
+
+          if include_decl && !output.start_with?(default_declaration_xml(doc, options))
+            return nil
+          end
+
+          output << "\n" unless output.end_with?("\n")
+          output
+        end
+
         def native_doctype_xml(doc)
           dt = doc.doctype
           return nil unless dt

data/lib/moxml/adapter/leptris.rb

@@ -106,6 +106,18 @@ module Moxml
           ctx = _context || Context.new(:leptris)
           doc = Document.new(native_doc, ctx)
 
+          if options[:noblanks]
+            # The engine's DROP_WS_TEXT trims boundary whitespace of
+            # NON-blank text nodes at parse (leptris/leptris#677), so
+            # the flag is never forwarded — blanks drop here instead.
+            if options[:readonly] == true
+              raise ArgumentError,
+                    "noblanks: true requires a mutable document (readonly: true freezes the tree at parse)"
+            end
+
+            strip_blank_text_nodes!(native_doc)
+          end
+
           record_source_declaration(native_doc, processed)
           attachments.set(native_doc, :entity_markers, entity_markers)
           attachments.set(native_doc, :parse_errors, recover_errors) if recover_errors
@@ -116,15 +128,57 @@ module Moxml
         # nil when no parse flag is requested — the binding treats a
         # nil options hash as plain defaults (matching libxml2/
         # Nokogiri semantics: blanks kept, no ATTLIST defaults).
-        # noblanks (issue #153) drops whitespace-only text nodes,
-        # libxml2 XML_PARSE_NOBLANKS parity.
+        # noblanks is deliberately absent: the engine's
+        # LEPTRIS_PARSE_DROP_WS_TEXT trims boundary whitespace of
+        # non-blank text nodes too (leptris/leptris#677), so moxml
+        # implements it itself after parse — see
+        # strip_blank_text_nodes!.
         def parse_flags(options)
           flags = 0
           flags |= ::Leptris::XML::ParseOptions::DTDATTR if options[:dtdattr] == true
-          flags |= ::Leptris::XML::ParseOptions::NOBLANKS if options[:noblanks] == true
           flags.zero? ? nil : ::Leptris::XML::ParseOptions.new(flags)
         end
 
+        # XML whitespace exactly — \v and \f are not XML space.
+        BLANK_TEXT_RE = /\A[ \t\r\n]*\z/
+
+        # libxml2's XML_PARSE_NOBLANKS semantics (issues #153/#156):
+        # drop WHOLLY-whitespace text nodes; the boundary spaces of
+        # text-bearing nodes stay (mixed content cannot be
+        # re-indented). Raw-pointer walk over the root subtree — the
+        # same batch child-pointer pattern the materializer uses.
+        def strip_blank_text_nodes!(doc)
+          binding_ffi = ::Leptris::XML::FFI
+          root = binding_ffi.leptris_document_root(doc.c_ptr)
+          return unless root && !root.null?
+
+          strip_blanks_under(root, binding_ffi, ::FFI::MemoryPointer.new(:pointer, 64), 64)
+        end
+
+        def strip_blanks_under(ptr, binding_ffi, buf, capacity)
+          count = binding_ffi.leptris_node_children(ptr, buf, capacity)
+          while count == capacity
+            capacity *= 4
+            buf = ::FFI::MemoryPointer.new(:pointer, capacity)
+            count = binding_ffi.leptris_node_children(ptr, buf, capacity)
+          end
+
+          # Snapshot before unlinking or recursing — both reuse the
+          # buffer for the next level.
+          children = buf.read_array_of_pointer(count)
+          children.each do |child|
+            case binding_ffi.leptris_node_get_type(child)
+            when ::Leptris::XML::FFI::NODE_ELEMENT
+              strip_blanks_under(child, binding_ffi, buf, capacity)
+            when ::Leptris::XML::FFI::NODE_TEXT
+              content = binding_ffi.leptris_text_node_get_content(child)
+              next unless content.match?(BLANK_TEXT_RE)
+
+              binding_ffi.check_status(binding_ffi.leptris_node_unlink(child))
+            end
+          end
+        end
+
         def parse_errors(native_doc)
           attachments.get(native_doc, :parse_errors) || NO_PARSE_ERRORS
         end

data/lib/moxml/document.rb

@@ -104,7 +104,12 @@ module Moxml
       node = prepare_node(node)
 
       if node.is_a?(Declaration)
-        # Mark that document now has a declaration
+        # A proper XML document carries at most one declaration
+        # (issue #23).
+        if @has_xml_declaration || adapter.has_declaration?(@native, self)
+          raise Moxml::ValidationError, "Document already has an XML declaration"
+        end
+
         @has_xml_declaration = true
         adapter.add_child(@native, node.native)
       elsif root && !node.is_a?(ProcessingInstruction) && !node.is_a?(Comment) && !node.is_a?(Doctype)

data/lib/moxml/node_set.rb

@@ -4,7 +4,7 @@ module Moxml
   class NodeSet
     include Enumerable
 
-    attr_reader :nodes, :context
+    attr_reader :context
 
     def initialize(nodes, context, parent_node = nil)
       @nodes = Array(nodes)
@@ -13,6 +13,13 @@ module Moxml
       @parent_node = parent_node
     end
 
+    # The raw native nodes — adapter-internal work only (issue #26).
+    # The public surface is wrapper-only: every Enumerable access
+    # goes through #each/#[]/#to_a, which wrap.
+    def native_nodes
+      @nodes
+    end
+
     def each
       return to_enum(:each) unless block_given?
 
@@ -64,7 +71,7 @@ module Moxml
     end
 
     def +(other)
-      self.class.new(@nodes + other.nodes, @context, @parent_node)
+      self.class.new(@nodes + other.native_nodes, @context, @parent_node)
     end
 
     def <<(node)

data/lib/moxml/version.rb

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

data/spec/integration/all_adapters_spec.rb

@@ -59,7 +59,15 @@ RSpec.describe "Cross-adapter integration" do
       end
 
       all_shared_examples.each do |shared_example_name|
-        it_behaves_like shared_example_name
+        # The performance battery runs only under RUN_PERFORMANCE /
+        # `rake spec:performance` (issue #45) - tagged at inclusion:
+        # definition-site metadata on the shared group does not
+        # propagate through this indirection.
+        if shared_example_name == "Performance Examples"
+          it_behaves_like shared_example_name, performance: true
+        else
+          it_behaves_like shared_example_name
+        end
       end
     end
   end

data/spec/integration/shared_examples/node_wrappers/declaration_behavior.rb

@@ -101,5 +101,11 @@ RSpec.shared_examples "Moxml::Declaration" do
       declaration.remove
       expect(doc.to_xml).not_to include("<?xml")
     end
+
+    it "rejects a second declaration (issue #23)" do
+      doc.add_child(doc.create_declaration("1.0"))
+      expect { doc.add_child(doc.create_declaration("1.0")) }
+        .to raise_error(Moxml::ValidationError, /already has an XML declaration/)
+    end
   end
 end

data/spec/moxml/adapter/leptris_spec.rb

@@ -185,31 +185,60 @@ RSpec.describe Moxml::Adapter::Leptris do
       expect(doc.to_xml).to include("<?renamed changed?>")
     end
 
-    it "matches raw Nokogiri with tab units on element-only trees" do
+    it "matches raw Nokogiri with tab units" do
       skip "requires the indent unit (leptris 1.9.45+)" unless described_class::INDENT_UNIT_SUPPORTED
 
-      source = %(<r><a><b/></a><c><d/><e/></c></r>)
-      target = Nokogiri::XML(source).to_xml(indent: 2, indent_text: "\t", encoding: "UTF-8")
-      output = ctx.parse(source).to_xml(
-        indent: 2, declaration: true, expand_empty: false,
-        encoding: "UTF-8", indent_text: "\t"
-      )
-      expect(output).to eq(target)
+      # Text-bearing children included since the engine fix for
+      # leptris/leptris#658 (leptris 1.9.46). Comment children are
+      # excluded: the binding's element+unit path drops them
+      # (leptris-ruby#115).
+      sources = [
+        %(<r><a><b/></a><c><d/><e/></c></r>),
+        %(<root><child>content</child><empty/></root>),
+        %(<r>text <b>bold</b> tail</r>),
+      ]
+      sources.each do |source|
+        target = Nokogiri::XML(source).to_xml(indent: 1, indent_text: "\t", encoding: "UTF-8")
+        output = ctx.parse(source).to_xml(
+          indent: 1, declaration: true, expand_empty: false,
+          encoding: "UTF-8", indent_text: "\t"
+        )
+        expect(output).to eq(target), "tab parity failed for #{source}"
+      end
     end
 
-    it "drops space-only text nodes with noblanks and matches Nokogiri (issue #153)" do
-      source = %(<a><t>1</t>    <n/></a>)
+    it "drops space-only text nodes with noblanks and matches Nokogiri (issues #153/#156)" do
+      sources = [
+        %(<a><t>1</t>    <n/></a>), # blank filler between tags
+        %(<p> leading</p>),                 # boundary space must survive
+        %(<p><b>b</b> after</p>),           # element-to-text space must survive
+        %(<p>trailing </p>),                # trailing space must survive
+        %(<r>\n  <a>x <b>y</b> z</a>\n  <c/>\n</r>),
+      ]
       recipe = {
         indent: 2, declaration: true, expand_empty: false, encoding: "UTF-8"
       }
-      target = Nokogiri::XML(source, &:noblanks).to_xml(indent: 2, encoding: "UTF-8")
 
-      doc = ctx.parse(source, noblanks: true)
+      sources.each do |source|
+        target = Nokogiri::XML(source, &:noblanks).to_xml(indent: 2, encoding: "UTF-8")
+
+        doc = ctx.parse(source, noblanks: true)
+        expect(doc.to_xml(recipe)).to eq(target), "noblanks parity failed for #{source}"
+
+        via_nokogiri = Moxml.new(:nokogiri).parse(source, noblanks: true).to_xml(recipe)
+        expect(via_nokogiri).to eq(target)
+      end
+    end
+
+    it "leaves no text nodes on a noblanks tree of blank filler" do
+      doc = ctx.parse(%(<a><t>1</t>    <n/></a>), noblanks: true)
       expect(doc.root.children.to_a.select(&:text?)).to be_empty
-      expect(doc.to_xml(recipe)).to eq(target)
+    end
 
-      via_nokogiri = Moxml.new(:nokogiri).parse(source, noblanks: true).to_xml(recipe)
-      expect(via_nokogiri).to eq(target)
+    it "refuses noblanks on readonly parses" do
+      # The strip mutates the tree; readonly freezes it at parse.
+      expect { ctx.parse("<a/>", noblanks: true, readonly: true) }
+        .to raise_error(ArgumentError, /noblanks.*mutable/)
     end
 
     it "reports the tracked native for a re-added document PI" do

data/spec/moxml/adapter/oga_spec.rb

@@ -13,12 +13,13 @@ RSpec.describe Moxml::Adapter::Oga do
   it_behaves_like "xml adapter"
 
   describe "serialization" do
-    it "does not duplicate XML declarations when declaration nodes repeat" do
+    it "rejects a repeated XML declaration instead of duplicating it (issue #23)" do
       context = Moxml::Context.new(:oga)
       doc = context.create_document
 
       doc.add_child(doc.create_declaration("1.0", "UTF-8"))
-      doc.add_child(doc.create_declaration("1.0", "UTF-8"))
+      expect { doc.add_child(doc.create_declaration("1.0", "UTF-8")) }
+        .to raise_error(Moxml::ValidationError)
       doc.add_child(doc.create_element("root"))
 
       serialized = doc.to_xml

data/spec/moxml/node_set_spec.rb

@@ -36,4 +36,16 @@ RSpec.describe Moxml::NodeSet do
       expect(nodes).to be_empty
     end
   end
+
+  describe "public surface (issue #26)" do
+    it "exposes raw natives only through native_nodes" do
+      children = doc.root.children
+      expect(children.native_nodes).not_to include(a_kind_of(Moxml::Node))
+      expect(children).not_to respond_to(:nodes)
+    end
+
+    it "wraps through the Enumerable surface" do
+      expect(doc.root.children.map(&:class).uniq).to eq([Moxml::Element])
+    end
+  end
 end

data/spec/performance/benchmark_spec.rb

@@ -4,9 +4,13 @@ require "benchmark"
 require "benchmark/ips"
 
 RSpec.shared_examples "Performance Examples" do
-  if ENV["SKIP_BENCHMARKS"]
-    it "skips benchmarks when SKIP_BENCHMARKS is set" do
-      skip "Benchmarks skipped. To run benchmarks, unset SKIP_BENCHMARKS"
+  # Issue #45: benchmarks never run inside the default suites - only
+  # under RUN_PERFORMANCE=1 (the CI perf step and
+  # rake spec:performance). RSpec tag exclusion proved unreliable
+  # through the shared-example indirection, so this is a hard env gate.
+  if ENV["SKIP_BENCHMARKS"] || !ENV["RUN_PERFORMANCE"]
+    it "skips benchmarks unless RUN_PERFORMANCE is set" do
+      skip "Benchmarks run only with RUN_PERFORMANCE=1 (rake spec:performance)"
     end
   else
     let(:context) { Moxml.new }
@@ -41,7 +45,7 @@ RSpec.shared_examples "Performance Examples" do
         }
       end
 
-      it "meets Parser performance threshold" do
+      it "meets Parser performance threshold", :performance do
         result = nil
         report = Benchmark.ips do |x|
           x.config(time: 5, warmup: 2)
@@ -54,7 +58,7 @@ RSpec.shared_examples "Performance Examples" do
         expect(ips).to be >= threshold, message
       end
 
-      it "meets Serializer performance threshold" do
+      it "meets Serializer performance threshold", :performance do
         report = Benchmark.ips do |x|
           x.config(time: 5, warmup: 2)
           x.report("Serializer") { _ = doc.to_xml }

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: moxml
 version: !ruby/object:Gem::Version
-  version: 0.5.18
+  version: 0.5.20
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-08-31 00:00:00.000000000 Z
+date: 2026-09-01 00:00:00.000000000 Z
 dependencies: []
 description: |
   Moxml is a unified XML manipulation library that provides a common API