moxml 0.5.148 → 0.5.149

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/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Moxml
-  VERSION = "0.5.148"
+  VERSION = "0.5.149"
 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"

data/lib/moxml.rb

@@ -102,6 +102,7 @@ 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"
 

data/spec/consistency/adapter_parity_spec.rb

@@ -1,5 +1,7 @@
 # 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>" }
 

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

data/spec/consistency/divergence_register_spec.rb

@@ -9,7 +9,7 @@ require "spec_helper"
 # no spec cites an unregistered ID.
 RSpec.describe "divergence register linkage" do
   REGISTER_PATH = "docs/_pages/divergences.adoc" # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
-  SCAN_GLOBS = %w[spec/consistency/**/*.rb spec/moxml/**/*.rb].freeze # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
+  SCAN_GLOBS = %w[spec/consistency/**/*.rb spec/moxml/**/*.rb spec/support/*.rb].freeze # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
   NEXT_GATE = [ # rubocop:disable Lint/ConstantDefinitionInBlock, RSpec/LeakyConstantDeclaration
     /same engine as/, # engine dedup, not a divergence
     /source_adapter == target_adapter/, # self round-trip
@@ -18,7 +18,15 @@ RSpec.describe "divergence register linkage" do
     /skip_shapes/,              # shape routing (IDs cited above)
     /leptris_fixed\?/,          # version gate
     /source_elements/,          # data-presence guard
+    /next unless doc/,          # adapter-availability guard (not a
+    # divergence: the adapter is not installed in this environment)
+    /next unless cell\[:pin\]/, # matrix data-presence guard
     /next unless match/,        # scanner-internal guard
+    /well_formed|voids\.empty\?|default_ns|per\.size/, # property-scope
+    # and availability guards (input scoping, not adapter exemptions)
+    /exempt/i, # value-routed exemption table: the
+    # table's VALUES are D-IDs, enforced by
+    # the coverage audit's exempt rule
   ].freeze
 
   # Version/availability gates are not divergences: a binding too old

data/spec/consistency/eol_normalization_spec.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# Processing model §Parsing (normative): pinned here.
+
 require "spec_helper"
 
 # XML 1.0 §2.11 End-of-Line Handling: literal CRLF and lone CR

data/spec/consistency/loud_degradation_spec.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+# Processing model §Errors and loud degradation (normative): pinned here.
+
 require "spec_helper"
 
 # Loud degradation (processing model, "Errors and loud degradation"):