moxml 0.5.149 → 0.5.151

data/lib/moxml/context.rb

@@ -90,7 +90,10 @@ module Moxml
     end
 
     def bump_children_generation
-      @children_generation = children_generation + 1
+      # One dispatch, not two: children_generation re-dispatched just
+      # to default nil. Shared counter — node wrappers' children memos
+      # key on it.
+      @children_generation = @children_generation.to_i + 1
     end
 
     def namespace_scope_generation
@@ -101,6 +104,22 @@ module Moxml
       @namespace_scope_generation += 1
     end
 
+    # Namespace scopes only need the per-mutation generation bump
+    # while namespaces can exist. A builder-only document (no parse,
+    # no xmlns write) never has one, and the bump sat on the attach
+    # hot path (deletion experiment: build row 2.128x -> 1.923x).
+    # Every namespace introduction route marks the context active
+    # first — parse faces and the xmlns attribute-write face — so
+    # the sticky flag never misses an introduction.
+    def namespace_scopes_active?
+      @namespace_scopes_active = false if @namespace_scopes_active.nil?
+      @namespace_scopes_active
+    end
+
+    def mark_namespaces_active!
+      @namespace_scopes_active = true
+    end
+
     def entity_registry
       @entity_registry ||= build_entity_registry
     end
@@ -128,6 +147,7 @@ module Moxml
       # Parse with adapter, passing self (context) so adapter can use our config
       parsed_options = default_options.merge(options)
       doc = config.adapter.parse(xml_string, parsed_options, self)
+      mark_namespaces_active!
 
       # Set declaration flag on Document wrapper (proper OOP)
       doc.has_xml_declaration = has_declaration if doc.is_a?(Document)
@@ -198,6 +218,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
@@ -220,7 +253,9 @@ module Moxml
     # are the result either way.
     def parse_fragment(xml)
       adapter = config.adapter
-      adapter.parse_fragment(xml, self).map do |node|
+      nodes = adapter.parse_fragment(xml, self)
+      mark_namespaces_active!
+      nodes.map do |node|
         # Adapters that tie a parent_node lifetime chain (#245)
         # return wrapped nodes — pass them through untouched;
         # re-wrapping would race the weak wrapper map.
@@ -229,6 +264,7 @@ module Moxml
     end
 
     def iterparse(xml, mode: :top_level, &block)
+      mark_namespaces_active!
       config.adapter.iterparse(xml, mode, self, &block)
     end
 
@@ -282,6 +318,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

@@ -163,7 +163,17 @@ module Moxml
     end
 
     def create_element(name)
-      native = adapter.create_element(name, owner_doc: @native)
+      # The preprimed mint (leptris binding with the C-primed
+      # create_element): the mint already wrote @context/@adapter in
+      # C, so the returned node IS the finished wrapper and the Ruby
+      # prime pass disappears from the build path.
+      native = if adapter.mints_primed?
+                 adapter.create_primed_element(name, owner_doc: @native,
+                                                     context: context,
+                                                     adapter: adapter)
+               else
+                 adapter.create_element(name, owner_doc: @native)
+               end
       # leptris-ruby#508 mints registered klasses at create: the node
       # IS a contract-carrying identity (@native is self) — prime it
       # in place instead of shelling a second wrapper (a raw mint
@@ -282,14 +292,28 @@ module Moxml
       end
     end
 
-    # Sugar over xpath: the first node of a node-set; scalar results
-    # (count(), string(), boolean()) pass through unwrapped and
-    # uniform across adapters.
+    # 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)
+      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)
+
+        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
     def add_element(name, attributes = {}, &block)
       elem = create_element(name)

data/lib/moxml/element.rb

@@ -276,6 +276,7 @@ module Moxml
     def add_namespace(prefix, uri)
       adapter.create_namespace(@native, prefix, uri,
                                namespace_validation_mode: context.config.namespace_validation_mode)
+      context.mark_namespaces_active!
       invalidate_namespace_cache!
       self
     rescue ValidationError => e
@@ -530,8 +531,19 @@ module Moxml
 
     # Clear the namespace caches and bump the context's scope
     # generation so every wrapper — including ones not reachable from
-    # any children cache — recomputes on next read.
+    # any children cache — recomputes on next read. While namespaces
+    # cannot exist (context.namespace_scopes_active? is false) the
+    # memos can only hold namespace-free reads, so skipping the whole
+    # body is exact — and the nil-assignment form would MATERIALIZE
+    # three unset ivars per attached node, which is the cost this
+    # gate exists to remove. Every introduction route — parse faces
+    # and the xmlns write face — marks the context BEFORE its own
+    # invalidation, so the introducing mutation still clears and
+    # bumps; in-scope reads are generation-keyed, so other wrappers
+    # recompute on the bump.
     def invalidate_namespace_cache!
+      return unless context.namespace_scopes_active?
+
       @namespaces = nil
       @namespace_definitions = nil
       @in_scope_namespaces = nil

data/lib/moxml/node.rb

@@ -30,12 +30,19 @@ module Moxml
     def prime_contract(native, context, adapter = nil, node_type = nil)
       @context = context
       @native = native
-      @parent_node = nil
-      @adapter = adapter
-      @node_type_cached = node_type
+      # @parent_node and @node_type_cached stay UNSET when empty —
+      # every reader is nil-tolerant, and a nil write materializes the
+      # ivar (object-shape transition) on every created node.
+      @adapter = adapter unless adapter.nil?
+      @node_type_cached = node_type unless node_type.nil?
       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
@@ -209,10 +216,16 @@ module Moxml
     def attach_child(node)
       context.bump_children_generation
       node = prepare_node(node)
-      adapter.add_child(@native, node.native)
+      oc = node.context
+      if !oc.nil? && !oc.equal?(context) &&
+          oc.namespace_scopes_active?
+        context.mark_namespaces_active!
+      end
+      a = adapter
+      a.add_child(@native, node.native)
       # Refresh native in case adapter changed identity (e.g., LibXML
       # doc.root=); stable-identity adapters skip the round trip.
-      unless adapter.native_identity_stable?
+      unless a.native_identity_stable?
         refreshed = adapter.actual_native(node.native, @native)
         node.refresh_native!(refreshed) if refreshed && refreshed != node.native
       end
@@ -226,7 +239,9 @@ module Moxml
     def attach_previous_sibling(node)
       context.bump_children_generation
       node = prepare_node(node)
-      adapter.add_previous_sibling(@native, node.native)
+      absorb_namespace_activity(node)
+      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 +254,31 @@ 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)
+      absorb_namespace_activity(node)
+      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
 
+    # A node adopted from ANOTHER context can carry namespaces this
+    # context's own faces (parse, xmlns writes) never saw; import the
+    # source context's activity flag so the gated scope-generation
+    # bump stays armed here too.
+    def absorb_namespace_activity(node)
+      oc = node.context
+      return if oc.nil? || oc.equal?(context)
+      context.mark_namespaces_active! if oc.namespace_scopes_active?
+    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 +330,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,14 +416,26 @@ module Moxml
       Materializer.materialize_fields(self, &block)
     end
 
-    # Sugar over xpath: the first node of a node-set; scalar results
-    # (count(), string(), boolean()) pass through unwrapped and
-    # uniform across adapters.
+    # 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 = {})
+      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
     # at/search auto-detect XPath vs CSS; the XPath-first fallback
     # covers the dominant caller shape (XPath expression strings)
@@ -732,7 +793,10 @@ module Moxml
     protected
 
     def invalidate_children_cache!
-      @children = nil
+      # Only nil an EXISTING memo: nil-assignment materializes an
+      # unset ivar (object-shape transition), and the builder hot
+      # path invalidates parents whose children memo was never read.
+      @children = nil unless @children.nil?
     end
 
     # Invalidate parent's cached children when this node
@@ -906,6 +970,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|
@@ -227,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/relaxng.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+module Moxml
+  # RELAX NG schema validation (TODO.sota/05): a facade for engines
+  # that ship an RNG validator. Engines without one raise the named
+  # Moxml::NotImplementedError — the face is never silently absent.
+  #
+  #     ctx    = Moxml.new(:leptris)
+  #     schema = ctx.relaxng_file("schema.rng")
+  #     schema.valid?(doc)            # => true/false
+  #     schema.validate_errors(doc)   # => [] or [{line:, column:, message:}]
+  #     schema.validate(doc)          # => [] or ["line:col: error: message"]
+  #
+  # Adapters without an engine raise at compile; RelaxNG.supported?
+  # answers without raising (the XSD facade's pattern).
+  module RelaxNG
+    class << self
+      # Whether the context's adapter ships a RELAX NG validator.
+      def supported?(context)
+        adapter = context.config.adapter
+        adapter.const_defined?(:RELAXNG_SUPPORTED) &&
+          adapter.const_get(:RELAXNG_SUPPORTED)
+      end
+    end
+
+    # A compiled schema (adapter-owned handle).
+    class Schema
+      def initialize(handle, context)
+        @handle = handle
+        @context = context
+      end
+
+      def valid?(document)
+        @context.config.adapter.relaxng_valid?(@handle, native(document))
+      end
+
+      # Structured report: [{line:, column:, message:}] (empty = valid).
+      def validate_errors(document)
+        @context.config.adapter
+          .relaxng_validate_errors(@handle, native(document))
+      end
+
+      # Nokogiri shape: error strings (empty = valid).
+      def validate(document)
+        validate_errors(document).map do |error|
+          line = error[:line]
+          if line&.to_i&.positive?
+            "#{line}:#{error[:column]}: error: #{error[:message]}"
+          else
+            error[:message]
+          end
+        end
+      end
+
+      private
+
+      def native(document)
+        document.is_a?(Moxml::Document) ? document.native : document
+      end
+    end
+  end
+end

data/lib/moxml/sax/block_handler.rb

@@ -191,6 +191,13 @@ module Moxml
       def on_warning(message)
         @handlers[:warning]&.call(message)
       end
+
+      # A block handler subscribes to a family only when its DSL block
+      # was registered — it overrides every callback, so method
+      # ownership cannot answer interest here.
+      def handles?(family)
+        @handlers.key?(family)
+      end
     end
   end
 end

data/lib/moxml/sax/handler.rb

@@ -98,6 +98,26 @@ module Moxml
         raise error
       end
 
+      # SAX event families that engines may or may not report as
+      # distinct events, with their handler methods. An engine that
+      # cannot report a family must raise the named error when the
+      # handler subscribes — never fold the events silently.
+      EVENT_METHODS = {
+        cdata: :on_cdata,
+        comment: :on_comment,
+        processing_instruction: :on_processing_instruction,
+      }.freeze
+
+      # Whether this handler subscribes to an event family: the
+      # callback was overridden (class handlers) or registered (block
+      # handlers).
+      #
+      # @param family [Symbol] one of EVENT_METHODS keys
+      # @return [Boolean]
+      def handles?(family)
+        method(EVENT_METHODS.fetch(family)).owner != Moxml::SAX::Handler
+      end
+
       # Called when a non-fatal warning occurs
       #
       # Default implementation ignores warnings.

data/lib/moxml/version.rb

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

data/lib/moxml/xpath.rb

@@ -26,5 +26,33 @@ module Moxml
       autoload :Node, "moxml/xpath/ruby/node"
       autoload :Generator, "moxml/xpath/ruby/generator"
     end
+
+    module_function
+
+    # Evaluate an expression through the pure-Ruby XPath 1.0 engine —
+    # the model's reference lane. Adapters route shapes their native
+    # engine cannot answer here (the `xmlns:` idiom, `text()` node
+    # tests, ...). Returns the engine's answer: an Array of wrapped
+    # nodes in document order, a NodeSet, or a scalar.
+    def evaluate(node, expression, namespaces = {}, adapter: nil)
+      context = node.is_a?(Moxml::Node) ? node.context : ::Moxml::Context.new(adapter)
+      wrapped = node.is_a?(Moxml::Node) ? node : Moxml::Node.wrap(node, context)
+      compiled = Compiler.compile_with_cache(Parser.parse(expression),
+                                             namespaces: namespaces)
+      compiled.call(wrapped)
+    end
+
+    # The adapter-contract form of #evaluate: Array<native> | scalar.
+    def evaluate_natives(node, expression, namespaces = {}, adapter: nil)
+      result = evaluate(node, expression, namespaces, adapter: adapter)
+      case result
+      when Array
+        result.map { |n| n.is_a?(Moxml::Node) ? n.native : n }
+      when NodeSet
+        result.to_a.map(&:native)
+      else
+        result
+      end
+    end
   end
 end

data/lib/moxml.rb

@@ -105,6 +105,7 @@ module Moxml
   autoload :Reference, "moxml/reference"
   autoload :XSLT, "moxml/xslt"
   autoload :XSD, "moxml/xsd"
+  autoload :RelaxNG, "moxml/relaxng"
 
   # Error hierarchy — each subclass autoloads from the same file
   autoload :Error, "moxml/error"

data/spec/consistency/adapter_parity_spec.rb

@@ -5,6 +5,28 @@
 RSpec.describe "Adapter Examples" do
   let(:xml) { "<root><child>text</child></root>" }
 
+  describe "Document children listing" do
+    it "never lists the XML declaration as a child" do
+      Moxml::Adapter::AVAILABLE_ADAPTERS.each do |adapter|
+        doc = Moxml.new(adapter)
+          .parse(%(<?xml version="1.0"?><r/>))
+        expect(doc.children.map(&:node_type)).to eq([:element]),
+                                                 "#{adapter}: declaration leaked " \
+                                                 "into children (model: state, not a node)"
+        expect(doc.has_xml_declaration).to be(true),
+                                           "#{adapter}: declaration state lost"
+      end
+    end
+
+    it "lists the doctype per the Nokogiri contract" do
+      Moxml::Adapter::AVAILABLE_ADAPTERS.each do |adapter|
+        doc = Moxml.new(adapter).parse(%(<!DOCTYPE r><r/>))
+        expect(doc.children.map(&:node_type)).to eq(%i[doctype element]),
+                                                 "#{adapter}: doctype listing"
+      end
+    end
+  end
+
   describe "Serialization consistency" do
     it "produces equivalent XML across adapters",
        skip: "No easy way to exclude the declaration from Nokogiri documents" do

data/spec/consistency/citation_hygiene_spec.rb

@@ -0,0 +1,30 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# Citation hygiene (TODO.sota/07): a spec or doc that calls a
+# divergence "pre-existing" or "documented" must resolve it to a
+# register ID (D-NN) on the same line. The register is the only place
+# such a claim is allowed to stand on its own.
+CITATION_PHRASE = /(?:\bpre-existing\b|\bpreexisting\b|\bdocumented (?:divergence|limitation)\b)/i
+
+RSpec.describe "divergence citations" do
+  def offenses(paths)
+    paths.flat_map do |path|
+      File.readlines(path).each_with_index.filter_map do |line, idx|
+        claim = line.match?(CITATION_PHRASE)
+        cited = line.match?(/D-\d+/)
+        "#{path}:#{idx + 1}: #{line.strip}" if claim && !cited
+      end
+    end
+  end
+
+  it "resolves every pre-existing/documented divergence claim to a register ID" do
+    paths = (Dir.glob("spec/**/*.rb") + Dir.glob("docs/**/*.adoc"))
+      .reject { |path| path.end_with?("citation_hygiene_spec.rb") }
+    found = offenses(paths)
+    expect(found).to be_empty,
+                     "name a D-NN (docs/_pages/divergences.adoc) or drop " \
+                     "the claim:\n#{found.join("\n")}"
+  end
+end