moxml 0.5.61 → 0.5.62

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 432ffb6c040c2b5689552a050b01835b792cde27ddc816981fd186fd83b9df7d
-  data.tar.gz: 917f7712e1799209f6d1c3f832fb5a3de492da5e570959a9d8bf2a8b4902d537
+  metadata.gz: 430e3a7e8c18cfa2c083ae9b263e9fedbaed03c109811980f0ca51de36507be7
+  data.tar.gz: 9644f7689ef2126884a6b11ecfcf9c532e0b2cae9cb44005b5b6b3434d96c7b4
 SHA512:
-  metadata.gz: b6f0a69c52df888bf9afbc2706e755d9844d8d65247720d887cc6fb34c8d855964f278d798b947bfb028ce58f32253ff6ed92101fcc2cf45fe28695170c23405
-  data.tar.gz: 90b841bd8eb58119a38dce5333a53f9b37abc70755e69a887c52ab4565d1101727a2dcc40903a4671b92a10d4ba1bd67ab712ac97d37bdd04861359dd4b09bba
+  metadata.gz: 9f89223d0bc12427916bb46220f79d957df704b878ea02dc11387c9096c6829f5309ed857a3faa4c1b9aee0697b3dfe2f7fa9f73fc5e083b6c1c0963bea11501
+  data.tar.gz: 5120f5700dd76a688576501a90ee2e6ffc443558cb89478dd23f2ea5a424d29dac41dd4df4cb9acc764451b81f84c5a03eed3d4ab734adfa276c7a1043bf54ce

data/.github/workflows/rake.yml

@@ -59,3 +59,8 @@ jobs:
           RUN_PERFORMANCE: "1"
           RUBY_YJIT_ENABLE: "1"
         run: bundle exec rake spec:performance
+
+      - name: Plan parity lock (plan vs raw-nokogiri CPU)
+        env:
+          LEPTRIS_BENCH_LOCK: "1"
+        run: bundle exec rake benchmark:plan

data/Rakefile

@@ -253,6 +253,16 @@ namespace :benchmark do
     sh "ruby", "benchmark/pipeline_bench.rb"
   end
 
+  # Plan-bench regression lock (#249 follow-up): Moxml::Plan vs the
+  # wrapper walk vs raw nokogiri on the consumer shape. With
+  # LEPTRIS_BENCH_LOCK=1 (CI) it exits 1 when plan time exceeds
+  # 1.5x raw nokogiri — the "raw-nokogiri CPU parity" regression
+  # tripwire.
+  desc "Plan materialization benchmark with raw-nokogiri parity lock"
+  task :plan do
+    sh "bundle exec ruby benchmark/plan_bench.rb"
+  end
+
   desc "Generate adapter benchmark report"
   task :report do
     ruby "benchmarks/generate_report.rb"

data/benchmark/plan_bench.rb

@@ -0,0 +1,118 @@
+# frozen_string_literal: true
+
+# Plan-bench regression lock (leptris follow-up to #249): the plan
+# path must stay at or near raw-nokogiri CPU parity on the consumer
+# shape. Run via `rake benchmark:plan` or with LEPTRIS_BENCH_LOCK=1
+# to enforce the ceiling (CI): plan <= nokogiri * 1.5 — failures
+# mean an adapter or plan change regressed the compiled walk.
+require "moxml"
+require "nokogiri"
+
+Field = Struct.new(:name, :unit, :value)
+Record = Struct.new(:id, :kind, :fields)
+Catalog = Struct.new(:records)
+
+parts = [%(<?xml version="1.0"?><catalog>)]
+150.times do |i|
+  parts << %(<record id="r#{i}" kind="k#{i % 3}">)
+  6.times { |j| parts << %(<field name="f#{j}" unit="u#{j}">value #{i}.#{j}</field>) }
+  parts << %(</record>)
+end
+parts << %(</catalog>)
+XML = parts.join
+
+CTX = Moxml.new(:leptris)
+
+PLAN = Moxml::Plan.new do
+  on("record") { |attrs, _t, fields| Record.new(attrs["id"], attrs["kind"], fields) }
+  on("field")  { |attrs, text, _k| Field.new(attrs["name"], attrs["unit"], text) }
+end
+
+def plan_run
+  records = PLAN.parse(XML, CTX)
+  raise "shape" unless records.size == 150 && records[7].fields[3].value == "value 7.3"
+
+  records
+end
+
+def wrapper_run
+  doc = CTX.parse(XML)
+  catalog = Catalog.new([])
+  doc.root.children.each do |rec|
+    next unless rec.is_a?(Moxml::Element)
+
+    record = Record.new(rec["id"], rec["kind"], [])
+    rec.children.each do |f|
+      next unless f.is_a?(Moxml::Element)
+
+      record.fields << Field.new(f["name"], f["unit"], f.text)
+    end
+    catalog.records << record
+  end
+  raise "shape" unless catalog.records.size == 150
+
+  catalog
+end
+
+def nokogiri_run
+  doc = Nokogiri::XML(XML)
+  catalog = Catalog.new([])
+  doc.root.children.each do |rec|
+    next unless rec.is_a?(Nokogiri::XML::Element)
+
+    record = Record.new(rec["id"], rec["kind"], [])
+    rec.children.each do |f|
+      next unless f.is_a?(Nokogiri::XML::Element)
+
+      record.fields << Field.new(f["name"], f["unit"], f.text)
+    end
+    catalog.records << record
+  end
+  raise "shape" unless catalog.records.size == 150
+
+  catalog
+end
+
+REPS = 200
+
+def bench(&block)
+  times = []
+  allocs = []
+  REPS.times do
+    GC.start
+    a0 = GC.stat(:total_allocated_objects)
+    t0 = Process.clock_gettime(Process::CLOCK_PROCESS_CPUTIME_ID)
+    yield
+    times << (Process.clock_gettime(Process::CLOCK_PROCESS_CPUTIME_ID) - t0)
+    allocs << (GC.stat(:total_allocated_objects) - a0)
+  end
+  [times.sort[times.size / 2] * 1e6, allocs.min]
+end
+
+# The parity lock needs the lean plan rows (binding 1.9.194.2+);
+# on older bindings the plan runs the generic fallback and the
+# ceiling is meaningless — report and exit clean.
+if Gem::Version.new(Leptris::VERSION) < Gem::Version.new("1.9.194.2")
+  puts "SKIP parity lock: leptris #{Leptris::VERSION} lacks snapshot_rows (needs 1.9.194.2)"
+  exit 0
+end
+
+# warm
+plan_run
+wrapper_run
+nokogiri_run
+
+plan_us,  plan_allocs  = bench { plan_run }
+wrap_us,  wrap_allocs  = bench { wrapper_run }
+nk_us,    nk_allocs    = bench { nokogiri_run }
+
+puts format("plan     (parse+materialize) %<t>8.0f us  %<a>7d allocs",
+            t: plan_us, a: plan_allocs)
+puts format("wrapper  (parse+walk)       %<t>8.0f us  %<a>7d allocs",
+            t: wrap_us, a: wrap_allocs)
+puts format("nokogiri (parse+walk)       %<t>8.0f us  %<a>7d allocs",
+            t: nk_us, a: nk_allocs)
+puts format("plan/nokogiri %<r>.2fx (ceiling 1.50x for the CI lock)",
+            r: plan_us / nk_us)
+
+exit(1) if ENV["LEPTRIS_BENCH_LOCK"] && plan_us > nk_us * 1.5

data/lib/moxml/adapter/base.rb

@@ -358,11 +358,15 @@ namespace_validation_mode: :strict)
           nil
         end
 
-        # Plan row stream (Moxml::Plan): yields |name, attrs_pairs
-        # (flat [k, v, ...]), first-text, depth| per element in
-        # document order (pre-order). Returns true when the adapter
-        # provided the stream; nil/false lets the plan run its
-        # generic wrapper walk.
+        # Plan row stream (Moxml::Plan) — ADAPTER CONTRACT. Yields
+        # |name, attrs_pairs (flat [k, v, ...]), first-text, depth|
+        # per element in document order (pre-order); first-text is
+        # the element's first text child or nil. Adapters implement
+        # this natively off their engine nodes (nokogiri, ox, oga,
+        # rexml, libxml, leptris do) — Moxml::Plan executes entirely
+        # on these rows with no wrapper materialization. This default
+        # returns nil, which makes Moxml::Plan fall back to the
+        # generic wrapper walk — correct but slow; last resort only.
         def plan_rows(_native)
           nil
         end

data/lib/moxml/adapter/libxml.rb

@@ -1312,6 +1312,38 @@ module Moxml
             dst[attr_name] = attr.value
           end
         end
+
+        # Plan row stream (Moxml::Plan contract): pre-order element
+        # rows straight off the LibXML nodes — no wrapper minting.
+        def plan_rows(native)
+          root = if native.is_a?(::LibXML::XML::Document)
+                   r = native.root
+                   return nil unless r
+
+                   r
+                 else
+                   native
+                 end
+
+          walk = lambda do |el, depth|
+            attrs = []
+            el.attributes.each do |attr|
+              attrs << attr.name << attr.value
+            end
+            first_text = nil
+            el.children.each do |c|
+              first_text ||= c.content if c.text?
+            end
+            yield(el.name, attrs, first_text, depth)
+            el.children.each do |c|
+              walk.call(c, depth + 1) if c.element?
+            end
+          end
+          walk.call(root, 0)
+          true
+        end
+
+        public :plan_rows
       end
 
       # Bridge between LibXML SAX and Moxml SAX

data/lib/moxml/adapter/nokogiri.rb

@@ -516,6 +516,25 @@ module Moxml
           attachments.set(native_doc, :xml_decl, nil)
         end
 
+        # Plan row stream (Moxml::Plan contract): pre-order element
+        # rows |name, attrs_pairs, first-text, depth| straight off
+        # the libxml2-backed nodes — no wrapper minting.
+        def plan_rows(native)
+          root = native.is_a?(::Nokogiri::XML::Document) ? native.root : native
+          return nil unless root
+
+          walk = lambda do |el, depth|
+            attrs = []
+            el.attribute_nodes.each { |a| attrs << a.name << a.value }
+            first_text = nil
+            el.children.each { |c| first_text ||= c.content if c.text? }
+            yield(el.name, attrs, first_text, depth)
+            el.element_children.each { |c| walk.call(c, depth + 1) }
+          end
+          walk.call(root, 0)
+          true
+        end
+
         private
 
         def build_declaration_attrs(version, encoding, standalone)
@@ -533,6 +552,10 @@ module Moxml
             hsh.merge(attr_name => value)
           end
         end
+
+        # Plan row stream (Moxml::Plan contract): pre-order element
+        # rows |name, attrs_pairs, first-text, depth| straight off
+        # the libxml2-backed nodes — no wrapper minting.
       end
 
       # Bridge between Nokogiri SAX and Moxml SAX

data/lib/moxml/adapter/oga.rb

@@ -643,6 +643,34 @@ module Moxml
 
           ::Moxml::Adapter::CustomizedOga::XmlGenerator.new(node).to_xml
         end
+
+        # Plan row stream (Moxml::Plan contract): pre-order element
+        # rows over Oga's Ruby node objects.
+        def plan_rows(native)
+          root = if native.is_a?(::Oga::XML::Document)
+                   native.children.find { |c| c.is_a?(::Oga::XML::Element) }
+                 else
+                   native
+                 end
+          return nil unless root.is_a?(::Oga::XML::Element)
+
+          walk = lambda do |el, depth|
+            attrs = []
+            el.attributes.each { |a| attrs << a.name << a.value }
+            first_text = nil
+            el.children.each do |c|
+              first_text ||= c.text if c.is_a?(::Oga::XML::Text)
+            end
+            yield(el.name, attrs, first_text, depth)
+            el.children.each do |c|
+              walk.call(c, depth + 1) if c.is_a?(::Oga::XML::Element)
+            end
+          end
+          walk.call(root, 0)
+          true
+        end
+
+        public :plan_rows
       end
 
       # Bridge between a parsed Oga DOM and Moxml SAX events.

data/lib/moxml/adapter/ox.rb

@@ -955,6 +955,35 @@ module Moxml
           output << "</#{elem.name}>"
           output
         end
+
+        # Plan row stream (Moxml::Plan contract): pre-order element
+        # rows over Ox's Ruby node objects.
+        def plan_rows(native)
+          root = if native.is_a?(::Ox::Document)
+                   nodes = native.nodes.grep(::Ox::Element)
+                   nodes.first
+                 else
+                   native
+                 end
+          return nil unless root.is_a?(::Ox::Element)
+
+          walk = lambda do |el, depth|
+            attrs = []
+            (el.attributes || {}).each { |k, v| attrs << k.to_s << v.to_s }
+            first_text = nil
+            (el.nodes || []).each do |c|
+              first_text ||= c if c.is_a?(::String)
+            end
+            yield(el.name.to_s, attrs, first_text, depth)
+            (el.nodes || []).each do |c|
+              walk.call(c, depth + 1) if c.is_a?(::Ox::Element)
+            end
+          end
+          walk.call(root, 0)
+          true
+        end
+
+        public :plan_rows
       end
     end
 

data/lib/moxml/adapter/rexml.rb

@@ -694,6 +694,24 @@ module Moxml
           )
           formatter.write(node, output)
         end
+
+        # Plan row stream (Moxml::Plan contract): pre-order element
+        # rows over REXML's Ruby node objects.
+        def plan_rows(native)
+          root = native.is_a?(::REXML::Document) ? native.root : native
+          return nil unless root
+
+          walk = lambda do |el, depth|
+            attrs = []
+            el.attributes.each { |k, v| attrs << k << v }
+            yield(el.name, attrs, el.text, depth)
+            el.elements.each { |c| walk.call(c, depth + 1) }
+          end
+          walk.call(root, 0)
+          true
+        end
+
+        public :plan_rows
       end
     end
 

data/lib/moxml/version.rb

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

data/spec/moxml/plan_conformance_spec.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Moxml::Plan adapter-contract conformance (leptris follow-up to
+# #249): every adapter must produce IDENTICAL plan results on the
+# same document, whether its plan_rows is a bulk C stream (leptris,
+# nokogiri, libxml) or a Ruby-native walk (ox, oga, rexml).
+PlanRow = Struct.new(:id, :kind, :fields)
+PlanCell = Struct.new(:name, :unit, :value)
+
+RSpec.describe "Moxml::Plan adapter conformance" do
+  # Single-line fixture: no inter-element whitespace text, so
+  # engines that differ on insignificant text still agree.
+  let(:xml) do
+    '<catalog><record id="r0" kind="k0"><field name="f0" unit="u0">v 0.0</field><field name="f1" unit="u1">v 0.1</field></record><record id="r1" kind="k1"><field name="f0" unit="u0">v 1.0</field></record></catalog>'
+  end
+
+  let(:plan) do
+    Moxml::Plan.new do
+      on("record") do |attrs, _text, fields|
+        PlanRow.new(attrs["id"], attrs["kind"], fields)
+      end
+      on("field") do |attrs, text, _kids|
+        PlanCell.new(attrs["name"], attrs["unit"], text)
+      end
+    end
+  end
+
+  ADAPTERS = %i[leptris nokogiri ox oga rexml libxml].freeze # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+
+  it "executes on every available adapter" do
+    available = ADAPTERS.select do |a|
+      ctx = Moxml.new(a)
+      ctx.parse(xml)
+      true
+    rescue StandardError
+      false
+    end
+    expect(available).not_to be_empty
+
+    results = available.to_h { |a| [a, plan.parse(xml, Moxml.new(a))] }
+
+    baseline = results[available.first]
+    results.each do |adapter, rows|
+      expect(rows).to eq(baseline), "adapter #{adapter} diverged"
+    end
+
+    expect(baseline.size).to eq(2)
+    expect(baseline[0].fields.map(&:value)).to eq(["v 0.0", "v 0.1"])
+  end
+
+  it "skips no element and preserves order" do
+    rows = plan.parse(xml, Moxml.new(:nokogiri))
+
+    expect(rows.map(&:id)).to eq(%w[r0 r1])
+  end
+
+  it "handles depth-3 nesting identically" do
+    deep = Moxml::Plan.new do
+      on("catalog") { |_a, _t, records| records }
+      on("record") { |attrs, _t, fields| [attrs["id"], fields] }
+      on("field") { |attrs, text, _| [attrs["name"], text] }
+    end
+
+    ADAPTERS.each do |a|
+      begin
+        ctx = Moxml.new(a)
+        ctx.parse(xml)
+      rescue StandardError
+        next
+      end
+      out = deep.parse(xml, ctx)
+      expect(out[0]).to eq(
+        [["r0", [["f0", "v 0.0"], ["f1", "v 0.1"]]],
+         ["r1", [["f0", "v 1.0"]]]],
+      )
+    end
+  end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: moxml
 version: !ruby/object:Gem::Version
-  version: 0.5.61
+  version: 0.5.62
 platform: ruby
 authors:
 - Ribose Inc.
@@ -39,6 +39,7 @@ files:
 - README.adoc
 - Rakefile
 - benchmark/pipeline_bench.rb
+- benchmark/plan_bench.rb
 - benchmarks/.gitignore
 - benchmarks/generate_report.rb
 - bin/console
@@ -488,6 +489,7 @@ files:
 - spec/moxml/opal_oga_smoke_spec.rb
 - spec/moxml/opal_rexml_adapter_spec.rb
 - spec/moxml/opal_smoke_spec.rb
+- spec/moxml/plan_conformance_spec.rb
 - spec/moxml/plan_spec.rb
 - spec/moxml/processing_instruction_spec.rb
 - spec/moxml/readonly_parse_spec.rb