moxml 0.5.148 → 0.5.150

data/lib/moxml/reference.rb

@@ -0,0 +1,205 @@
+# frozen_string_literal: true
+
+module Moxml
+  # Executable reference semantics (TODO.sota/03): a pure-Ruby XML
+  # reader, writer, and normalizer that answer the processing model
+  # without any native engine. Adapters are differentially tested
+  # against these answers; the reference is also the lane for
+  # engine-free environments (the Opal line generalized).
+  #
+  # The reference is deliberately small and total over the model's
+  # declared input taxonomy — every well-formed document the model
+  # admits is parseable here. It is an oracle, not a production
+  # parser: no recovery, no diagnostics beyond a named ParseError.
+  module Reference
+    autoload :Parser, "moxml/reference/parser"
+    autoload :Writer, "moxml/reference/writer"
+    autoload :Normalizer, "moxml/reference/normalizer"
+
+    # A reference node: the information set of the processing model,
+    # with no engine-specific shape.
+    class Node
+      attr_accessor :kind, :name, :attributes, :children, :data, :parent
+
+      def initialize(kind:, name: nil, data: nil, attributes: [])
+        @kind = kind
+        @name = name
+        @data = data
+        @attributes = attributes
+        @children = []
+        @parent = nil
+      end
+
+      def element?
+        @kind == :element
+      end
+
+      def text?
+        @kind == :text
+      end
+
+      # The facade's name face: a bare local name for prefixed sources
+      # (Element#name; attribute pairs list bare names too).
+      def local_name
+        return @name unless @name&.include?(":")
+
+        @name.split(":", 2)[1]
+      end
+
+      # Concatenated descendant text (elements; text and CDATA only —
+      # comments and PI data are not text); own data for text-like
+      # nodes (the model's `text` face).
+      def text
+        case @kind
+        when :element
+          @children.select do |child|
+            child.kind == :text || child.kind == :cdata || child.element?
+          end.map(&:text).join
+        when :text, :cdata
+          @data
+        else
+          ""
+        end
+      end
+
+      # Element content is its text face; text-like nodes answer their
+      # data (PI data excludes the separator, per the model).
+      def content
+        element? ? text : @data
+      end
+
+      def attribute(name)
+        pair = @attributes.find do |(key, _)|
+          key == name || local_name_of(key) == name
+        end
+        pair && pair[1]
+      end
+
+      # The facade's listing face: bare names, source order, duplicates
+      # included, namespace declarations excluded (they are Namespace
+      # nodes, not attributes — uniform with every adapter).
+      def attribute_pairs
+        @attributes.filter_map do |(key, value)|
+          next if key == "xmlns" || key.start_with?("xmlns:")
+
+          [local_name_of(key), value]
+        end
+      end
+
+      def local_name_of(name)
+        return name unless name&.include?(":")
+
+        name.split(":", 2)[1]
+      end
+    end
+
+    # A reference document: declaration and doctype are state (the
+    # model's document-parts-are-state rule); children are the
+    # top-level nodes excluding them.
+    class Document
+      attr_accessor :children, :declaration, :doctype, :entities
+
+      def initialize
+        @children = []
+        @declaration = nil
+        @doctype = nil
+        @entities = {}
+      end
+
+      def root
+        @children.find(&:element?)
+      end
+
+      # Depth-first pre-order, excluding the document itself.
+      def each_node(&block)
+        @children.each { |child| walk(child, &block) }
+      end
+
+      def walk(node, &block)
+        yield node
+        node.children.each { |child| walk(child, &block) }
+      end
+    end
+
+    # Encodings the reference accepts: UTF-8 and US-ASCII sources.
+    # Transcoding is the adapter's business; the reference reads the
+    # UTF-8 string the facade hands it.
+    module_function
+
+    # Parse an XML string into a reference Document.
+    def parse(xml)
+      Parser.new(xml).parse
+    end
+
+    # Document-order element names (the ordering face; bare local
+    # names, matching Element#name).
+    def element_names(document)
+      names = []
+      document.each_node { |node| names << node.local_name if node.element? }
+      names
+    end
+
+    # Element children names, keyed by each element's index in
+    # pre-order (the children-listing face; avoids text segmentation,
+    # which is a registered engine divergence family).
+    def child_element_names(document)
+      rows = []
+      document.each_node do |node|
+        next unless node.element?
+
+        rows << node.children.select(&:element?).map(&:local_name)
+      end
+      rows
+    end
+
+    # The access truth table, one row per element in pre-order:
+    # [name, text, content].
+    def element_access_rows(document)
+      rows = []
+      document.each_node do |node|
+        next unless node.element?
+
+        rows << [node.local_name, node.text, node.content]
+      end
+      rows
+    end
+
+    # PI targets and data, in document order.
+    def processing_instructions(document)
+      rows = []
+      document.each_node do |node|
+        rows << [node.name, node.data] if node.kind == :processing_instruction
+      end
+      rows
+    end
+
+    # Comment data, in document order.
+    def comments(document)
+      rows = []
+      document.each_node { |node| rows << node.data if node.kind == :comment }
+      rows
+    end
+
+    # Serialize the reference document as XML (indent: 0 canonical
+    # facade shape: declaration if the source had one, escaped text,
+    # self-closing empty elements).
+    def to_xml(document)
+      Writer.new(document).to_xml
+    end
+
+    # Serialize as HTML (void elements unclosed, raw script/style).
+    def to_html(document)
+      Writer.new(document).to_html
+    end
+
+    # Serialize as XHTML (void elements self-closed).
+    def to_xhtml(document)
+      Writer.new(document).to_xhtml
+    end
+
+    # EOL normalization per XML 1.0 §2.11.
+    def normalize_eol(text)
+      Normalizer.normalize_eol(text)
+    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.148"
+  VERSION = "0.5.150"
 end

data/lib/moxml/xpath/compiler.rb

@@ -30,9 +30,12 @@ module Moxml
       # Wildcard for node names/namespace prefixes
       STAR = "*"
 
-      # Node types that require a NodeSet to push nodes into
+      # Node types that require a NodeSet to push nodes into.
+      # :union belongs here: a top-level union built its own NodeSet
+      # in on_pipe and bypassed the document-order wrapper — union
+      # results answered in expression order (M3).
       RETURN_NODESET = %i[path absolute_path relative_path axis
-                          predicate].freeze
+                          predicate union].freeze
 
       # Compiles and caches an AST
       #
@@ -94,8 +97,14 @@ module Moxml
                                          [nodeset_class, "new", empty_array,
                                           context_var])
 
+            # Multi-step paths batch step N over every step-(N-1)
+            # node, concatenating subtree results after sibling
+            # results (//* answered a,c,b on <r><a><b/></a><c/></r>);
+            # XPath path results are conventionally document-ordered.
+            ordered = Ruby::Node.new(:send, [matched, "document_order"])
             body = matched.assign(nodeset_new)
               .followed_by(ruby_ast)
+              .followed_by(matched.assign(ordered))
               .followed_by(matched)
           else
             body = ruby_ast
@@ -293,6 +302,12 @@ module Moxml
                 end
               end
             end
+
+          # Multi-step evaluation batches step N over every step-(N-1)
+          # node, so subtree results concatenate after sibling
+          # results (//* on <r><a><b/></a><c/></r> answered a,c,b).
+          # Path results are conventionally document-ordered: re-sort
+          # the union when the caller takes the node-set form.
         end
       end
 

data/lib/moxml/xpath/ordering.rb

@@ -0,0 +1,97 @@
+# frozen_string_literal: true
+
+module Moxml
+  module XPath
+    # Document ordering for node-set results (TODO.sota/02, M3).
+    #
+    # XPath defines node-sets as unordered, but path-expression
+    # results are conventionally in document order (and consumers
+    # rely on it). Multi-step paths are evaluated by batching step N
+    # over every step-(N-1) node, which concatenates subtree results
+    # after sibling results — results must therefore be re-ordered.
+    #
+    # Ordering is a ONE-PASS position index per document, keyed by
+    # native identity: `traverse` yields nodes in document order, and
+    # the engines that re-order here (oga; the pure-Ruby XPath engine
+    # lanes) expose stable native objects per node. The ancestry-walk
+    # key (`key_for`) is quadratic on wide documents — every node
+    # compares its way through its siblings' structural equality —
+    # and is kept only as a fallback for natives the index does not
+    # know (attribute results, unstable identities).
+    module Ordering
+      module_function
+
+      INDEXED_ELEMENT_RANK = 1
+      ATTRIBUTE_RANK = 0
+      FALLBACK_RANK = 2
+
+      # Below this result size the ancestry walk is cheaper than one
+      # document traverse (the index only pays off on wide results).
+      INDEX_THRESHOLD = 16
+
+      # Sorts wrappers into document order. Attributes sort before
+      # the children of their element (XPath attribute-then-child
+      # ordering). Nodes the index cannot place keep their relative
+      # position at the end (stable sort).
+      def document_order(nodes)
+        return nodes if nodes.size < 2
+
+        indexed = if nodes.size < INDEX_THRESHOLD
+                    nodes.each_with_index.map do |node, i|
+                      [fallback_key(node), i, node]
+                    end
+                  else
+                    positions = position_index(nodes.first)
+                    nodes.each_with_index.map do |node, i|
+                      [positions.fetch(node.native) { fallback_key(node) },
+                       i, node]
+                    end
+                  end
+        indexed.sort_by { |key, i, _| [key, i] }.map(&:last)
+      end
+
+      # native => [rank, position] for every node in document order.
+      # compare_by_identity: the natives are the engine's own objects,
+      # and native equality may be structural (Oga compares subtrees).
+      def position_index(node)
+        doc = node
+        doc = doc.parent while doc && !doc.is_a?(Moxml::Document)
+        return {}.compare_by_identity unless doc
+
+        index = {}.compare_by_identity
+        position = 0
+        doc.traverse do |n|
+          index[n.native] = [INDEXED_ELEMENT_RANK, position]
+          position += 1
+        end
+        index
+      end
+
+      # Documents with unstable native wrappers (a fresh object per
+      # access) fall back to the ancestry path: correct, and only the
+      # answer for lanes whose engine already orders natively.
+      def fallback_key(node)
+        kind_rank = node.is_a?(Moxml::Attribute) ? ATTRIBUTE_RANK : FALLBACK_RANK
+        [kind_rank, ancestry_path(node)]
+      end
+
+      def ancestry_path(node)
+        path = []
+        current = node
+        while current && !current.is_a?(Moxml::Document)
+          parent = current.parent
+          break unless parent
+
+          siblings = parent.children.to_a
+          idx = siblings.index { |s| s.equal?(current) } ||
+            siblings.index(current)
+          return [2_000_000] if idx.nil?
+
+          path.unshift(idx)
+          current = parent
+        end
+        path
+      end
+    end
+  end
+end

data/lib/moxml/xpath.rb

@@ -9,6 +9,7 @@ module Moxml
     autoload :Lexer, "moxml/xpath/lexer"
     autoload :Parser, "moxml/xpath/parser"
     autoload :Compiler, "moxml/xpath/compiler"
+    autoload :Ordering, "moxml/xpath/ordering"
 
     autoload :Error, "moxml/xpath/errors"
     autoload :SyntaxError, "moxml/xpath/errors"
@@ -25,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

@@ -102,8 +102,10 @@ module Moxml
   autoload :SAX, "moxml/sax"
   autoload :Signature, "moxml/signature"
   autoload :C14n, "moxml/c14n"
+  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

@@ -1,8 +1,32 @@
 # frozen_string_literal: true
 
+# Processing model §Document order and traversal (normative): pinned here.
+
 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

data/spec/consistency/differential_taxonomy_spec.rb

@@ -0,0 +1,117 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+require "support/input_taxonomy"
+
+# Whole-class differential (TODO.sota/01): for every taxonomy input,
+# every available adapter answers the same observable results — or the
+# difference cites a registered divergence (D-NN). Faces: node count,
+# root name, text, element count via XPath. Plus M1 (parse∘serialize
+# round-trip) per adapter over every well-formed input. Nothing is
+# exempt without a D-ID: this is the generated-evidence face of the
+# conformance relation.
+
+RSpec.describe "cross-adapter taxonomy differential" do
+  def snapshot(doc)
+    {
+      nodes: doc.traverse.to_a.grep_v(Moxml::Document).count,
+      root: doc.root&.name,
+      text: doc.text,
+      xpath: doc.xpath("//*").to_a.count,
+    }
+  end
+
+  def answers(xml)
+    Moxml::Adapter::AVAILABLE_ADAPTERS.filter_map do |name|
+      doc = Moxml.new(name).parse(xml)
+      [name, snapshot(doc)]
+    rescue Moxml::Error, NotImplementedError, LoadError
+      nil # adapter unavailable in this environment
+    end.to_h
+  end
+
+  InputTaxonomy.well_formed.each do |input|
+    it "answers #{input.id} identically across adapters" do
+      per = answers(input.xml)
+      expect(per.keys.count).to be >= 2
+
+      base_name = per.keys.first
+      base = per[base_name]
+      per.each do |name, got|
+        base.except(:text).each_key do |face|
+          exempt = InputTaxonomy::EXEMPT.dig(input.id, face, name)
+          next if exempt
+
+          expect(got[face]).to eq(base[face]),
+                               "#{input.id}/#{face} differs on #{name} vs " \
+                               "#{base_name}: #{got[face].inspect} vs " \
+                               "#{base[face].inspect} — fix it or register " \
+                               "a divergence and exempt the cell"
+        end
+        text_exempt = InputTaxonomy::EXEMPT.dig(input.id, :text, name)
+        next if text_exempt
+
+        expect(got[:text]).to eq(base[:text]),
+                              "#{input.id}/text differs on #{name} vs " \
+                              "#{base_name}: #{got[:text].inspect} vs " \
+                              "#{base[:text].inspect} — fix it or register " \
+                              "a divergence and exempt the cell"
+      end
+    end
+  end
+
+  it "keeps the round trip stable per adapter (M1: parse∘serialize)" do # rubocop:disable RSpec/NoExpectationExample
+    InputTaxonomy.well_formed.each do |input|
+      Moxml::Adapter::AVAILABLE_ADAPTERS.each do |name|
+        begin
+          ctx = Moxml.new(name)
+          doc = ctx.parse(input.xml)
+          first = snapshot(doc)
+          # indent: 0 — default indentation synthesizes whitespace text
+          # nodes on re-parse (formatting, not information; D-09
+          # adapters ignore the knob and may embed their own pretty
+          # newlines regardless). M1 therefore compares the information
+          # set: root, element count, whitespace-collapsed text. Node
+          # COUNT identity is the cross-adapter face's job (same parse),
+          # not the round-trip's.
+          second = snapshot(ctx.parse(doc.to_xml(indent: 0)))
+        rescue Moxml::Error, NotImplementedError, LoadError
+          # Named guards (e.g. D-16's read cap on rexml) legitimately
+          # excuse an adapter from M1 for an input.
+          next
+        end
+        compact = ->(snap) {
+          snap.except(:nodes).merge(text: snap[:text].gsub(/\s+/, ""))
+        }
+        expect(compact.call(second)).to eq(compact.call(first)),
+                                        "#{input.id} round-trip drifted on " \
+                                        "#{name}: #{first.inspect} vs " \
+                                        "#{second.inspect}"
+      end
+    end
+  end
+
+  it "raises the named parse error on strict malformed input, everywhere" do
+    # Entity/reference and namespace-validation classes are
+    # engine-variant by design — moxml governs them with config
+    # (entity modes, namespace validation), not with a registered
+    # divergence.
+    engine_variant = %w[undefined reference undeclared prefix].freeze
+    inputs = InputTaxonomy.malformed.reject do |input|
+      engine_variant.any? { |term| input.id.include?(term) }
+    end
+
+    inputs.each do |input|
+      Moxml::Adapter::AVAILABLE_ADAPTERS.each do |name|
+        next if InputTaxonomy::STRICT_EXEMPT.dig(input.id, name)
+
+        # The strict lane, named: the model's default posture for
+        # malformed input is a named raise on every adapter.
+        expect { Moxml.new(name).parse(input.xml, strict: true) }
+          .to raise_error(Moxml::ParseError),
+              "#{input.id}/#{name}: strict parse accepted malformed " \
+              "input or raised outside the named ParseError contract"
+      end
+    end
+  end
+end