moxml 0.5.127 → 0.5.128

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 01032e6367e81d2b15512e378e32065aaaeda8e0159ab361b1cce56c853483b6
-  data.tar.gz: f7ea3e5da35d715e4c0ee624bd34fa2ed2b0e97114941e19aa623e737935ba8a
+  metadata.gz: 5b80e9601eb4a227d342aa484359a4724f3273a561c9f74cd8d375ffd5321186
+  data.tar.gz: 987e9faa827418fe3471456b1b939ced916467c895454670c3ba1273ee5fd616
 SHA512:
-  metadata.gz: 5738ff3e0b4b905ec4109aa4ec708885d2d901f322ef819bea1e54af264b7494c7f1fd65f58a83545d5a537175657174677970b584ad971b8c850ca3e37e85f1
-  data.tar.gz: 346e74335cc99fc6ade2d2502e6c1f628d6f5cf94fe8ac3e3dbe70e54641aff44b7926e0fb0b389ce501ba82633f71c936f1355ce1607ce71bb1c325fb90d265
+  metadata.gz: 0f059f790d6a76ba2213d83ced97289d837ab0ad1b4448dd1f026bb991a5e90b8131fabc31d6f2f0eeb948564693231ea89c3899a542618d65de153db687bde7
+  data.tar.gz: edae98439cf51d03ea590709a22fa05848f9e7b62fa7f274bf6e1ffdd34f0115eca0622b165e3f1a884d8f9a73ba4047338061d6281c4c88161ce13bbd44a7ae

data/Gemfile

@@ -9,7 +9,7 @@ gemspec
 gem "benchmark"
 gem "benchmark-ips"
 gem "get_process_mem"
-gem "leptris", "~> 1.9.341"
+gem "leptris", "~> 1.9.343"
 gem "libxml-ruby", ">= 5.0"
 gem "nokogiri", "~> 1.18"
 gem "openssl", "~> 3.0"

data/lib/moxml/adapter/base.rb

@@ -327,6 +327,15 @@ module Moxml
 
         def xsd_compile_error(_xsd_handle); end
 
+        # Deterministic drop (#362.3): true when the engine-side
+        # schema was freed NOW, false when the adapter can only
+        # wait for GC (the default — document the capability per
+        # adapter). moxml's Schema#release surfaces this. The name
+        # is the contract (release), not a predicate.
+        def xsd_release(_xsd_handle) # rubocop:disable Naming/PredicateMethod
+          false
+        end
+
         def xsd_simple_valid?(_xsd_handle, _type_name, _lexical)
           raise Moxml::NotImplementedError,
                 "XSD validation requires an adapter with an XSD engine"

data/lib/moxml/adapter/leptris.rb

@@ -198,6 +198,15 @@ module Moxml
 
       XSD_SUPPORTED = NATIVE_XSD
 
+      # Schema#release (moxml#362.3, binding 1.9.342+): the
+      # deterministic drop face — disarms the AutoPointer's GC
+      # finalizer and frees now. Face-probed with the version
+      # floor (the NATIVE_DOC_ABSORB pairing).
+      XSD_RELEASE =
+        Gem::Version.new(::Leptris::VERSION) >= Gem::Version.new("1.9.342.0") &&
+        defined?(::Leptris::XML::XSD::Schema) &&
+        ::Leptris::XML::XSD::Schema.method_defined?(:release)
+
       NATIVE_BUILDER =
         defined?(::Leptris::XML::Builder) &&
         defined?(::Leptris::XML::Document) &&
@@ -282,6 +291,12 @@ module Moxml
           xsd_handle.declaration_count
         end
 
+        def xsd_release(xsd_handle)
+          return false unless XSD_RELEASE
+
+          xsd_handle.release
+        end
+
         def xsd_compile_error(xsd_handle)
           xsd_handle.error
         end
@@ -300,17 +315,28 @@ module Moxml
 
         def xsd_validate(xsd_handle, native_document)
           # +xsd_handle+ is the binding's Leptris::XML::XSD::Schema;
-          # validate_errors takes the binding document. Entries
-          # normalize to Strings: the moxml contract is []-of-
-          # messages, and the binding may enrich entries into
-          # structured objects (element/line/column —
-          # leptris-ruby#419) without breaking consumers.
+          # validate_errors takes the binding document. Entries are
+          # the #362.2 ValidationError contract; the engine payload
+          # is message strings today (line/column/path ride
+          # leptris-ruby#419 — the mapping fills them the day the
+          # binding exposes them).
           doc = if native_document.is_a?(::Leptris::XML::Document)
                   native_document
                 else
                   to_binding(native_document)
                 end
-          xsd_handle.validate_errors(doc).map(&:to_s)
+          structured = defined?(::Leptris::XML::XSD::ValidationError)
+          xsd_handle.validate_errors(doc).map do |entry|
+            if structured &&
+                entry.is_a?(::Leptris::XML::XSD::ValidationError)
+              Moxml::XSD::ValidationError.new(
+                message: entry.message, line: entry.line,
+                column: entry.column, path: entry.path
+              )
+            else
+              Moxml::XSD::ValidationError.new(message: entry.to_s)
+            end
+          end
         end
 
         def builder_face(native_document)

data/lib/moxml/adapter/nokogiri.rb

@@ -10,6 +10,11 @@ module Moxml
       # libxslt-backed XSLT 1.0 (Moxml::XSLT contract).
       XSLT_SUPPORTED = true
 
+      # XSD over libxml2 (issue #362.2): structured #362
+      # ValidationError entries — libxml2 carries line/column in
+      # the message ("L:C: SEV: ..."), which the mapping lifts.
+      XSD_SUPPORTED = true
+
       class << self
         def attachments
           @attachments ||= Moxml::NativeAttachment.new
@@ -193,6 +198,57 @@ module Moxml
           native_fragment.children.map(&:to_html).join
         end
 
+        def xsd_compile(schema_source)
+          ::Nokogiri::XML::Schema.new(schema_source.to_s)
+        end
+
+        def xsd_compile_file(path)
+          path = path.to_s
+          # libxml2 resolves schemaLocation hrefs against the
+          # process CWD (the reader form carries no base) — chdir
+          # to the file's directory so relative hrefs resolve like
+          # leptris's engine-side base_dir.
+          dir = File.dirname(File.expand_path(path))
+          Dir.chdir(dir) { ::Nokogiri::XML::Schema(File.read(path)) }
+        end
+
+        # Compile failures RAISE from Schema.new; a constructed
+        # handle carries any pooled errors here (empty = none).
+        # Nokogiri/libxml2's schema object does not expose a
+        # declaration census — the base's nil default documents
+        # the capability gap rather than guessing.
+        def xsd_declarations(_xsd_handle)
+          nil
+        end
+
+        def xsd_compile_error(xsd_handle)
+          msgs = xsd_handle.errors.map(&:to_s)
+          msgs.empty? ? nil : msgs.join("; ")
+        end
+
+        def xsd_validate(xsd_handle, native_document)
+          xsd_handle.validate(native_document).map do |entry|
+            line = entry.line
+            line = line.to_i if line.is_a?(String)
+            Moxml::XSD::ValidationError.new(
+              message: strip_libxml2_position(entry.message),
+              line: line&.positive? ? line : nil,
+              column: nil,
+            )
+          end
+        end
+
+        # libxml2's nokogiri face prefixes "L:C: SEVERITY: " onto
+        # the message; the position rides the structured fields.
+        def strip_libxml2_position(message)
+          msg = message.to_s
+          if (m = msg.match(/\A\d+:\d+: (?:ERROR|WARNING|FATAL): (.*)\z/m))
+            m[1]
+          else
+            msg
+          end
+        end
+
         # Nokogiri parses with `config.recover` unless strict, so
         # recoverable syntax errors land on `doc.errors` instead of
         # raising (issue #147).

data/lib/moxml/css.rb

@@ -0,0 +1,275 @@
+# frozen_string_literal: true
+
+module Moxml
+  # CSS selector -> XPath 1.0 translation (#362.1): the shared
+  # implementation behind Node#css/at_css. One translator for
+  # every adapter — CSS semantics converge by construction instead
+  # of per-engine differences. Supported: type/universal, #id,
+  # .class, attribute predicates ([a], [a=v], ^=, $=, *=, ~=, |=),
+  # the descendant/child/adjacent-sibling/following-sibling
+  # combinators, :first-child/:last-child/:nth-child(n|odd|even),
+  # :not(simple), and comma groups (union NodeSets).
+  module Css
+    class Error < Moxml::Error; end
+
+    SIMPLE_PART = /
+      (?<tag>^[A-Za-z][\w-]*|\*)
+      | \.(?<class>[\w-]+)
+      | \#(?<id>[\w-]+)
+      | :(?<pseudo>[\w-]+(?:\([^)]*\))?)
+      | \[(?<attr>[^\]]+)\]
+    /x
+
+    module_function
+
+    # absolute: true when the context node is a DOCUMENT — the
+    # "//" anchor addresses the whole tree (and avoids engines
+    # that resolve "." at a document node to the root element);
+    # false (an element) scopes to the subtree with ".//".
+    def to_xpath(selector, absolute: false)
+      selectors = split_top_level(selector.to_s)
+      raise Error, "empty selector" if selectors.empty?
+
+      anchor = absolute ? "" : "."
+      selectors.map { |s| "#{anchor}#{to_xpath_one(s.strip)}" }
+        .uniq.join(" | ")
+    end
+
+    # Bracket- and quote-aware tokenization: combinator characters
+    # only split OUTSIDE [...] (a ~= inside an attribute selector
+    # is not the sibling combinator).
+    def tokenize(selector)
+      tokens = []
+      current = +""
+      depth = 0
+      quote = nil
+      flush = lambda do
+        unless current.empty?
+          tokens << [:simple, current]
+          current = +""
+        end
+      end
+      selector.each_char do |c|
+        if quote
+          current << c
+          quote = nil if c == quote
+        elsif ["'", '"'].include?(c)
+          quote = c
+          current << c
+        elsif c == "[" || c == "]" || depth.positive?
+          depth += 1 if c == "["
+          depth -= 1 if c == "]"
+          current << c
+        elsif c.match?(/[\s>+~]/)
+          flush.call
+          if tokens.last && tokens.last[0] == :comb
+            # a concrete combinator replaces the whitespace run;
+            # extra whitespace after one collapses
+            if c.match?(/[>+~]/)
+              tokens[-1] = [:comb, c]
+            end
+            next
+          end
+          tokens << [:comb, c.strip.empty? ? " " : c]
+        elsif c == ","
+          flush.call
+          tokens << [:comma, ","]
+        else
+          current << c
+        end
+      end
+      flush.call
+      tokens
+    end
+
+    def to_xpath_one(selector)
+      xpath = ""
+      seen_step = false
+      pending_combinator = :descendant
+
+      tokenize(selector).each do |kind, value|
+        if kind == :comb
+          raise Error, "selector starts with a combinator" unless seen_step
+
+          pending_combinator =
+            case value.strip
+            when ">" then :child
+            when "+" then :adjacent
+            when "~" then :sibling
+            else :descendant
+            end
+        elsif kind == :comma
+          raise Error, "trailing comma"
+        else
+          step = simple_selector_to_xpath(value, pending_combinator)
+          sep = if !seen_step
+                  pending_combinator == :descendant ? "//" : "/"
+                elsif pending_combinator == :descendant
+                  "//"
+                else
+                  "/"
+                end
+          xpath = "#{xpath}#{sep}#{step}"
+          seen_step = true
+          pending_combinator = :descendant
+        end
+      end
+
+      raise Error, "selector ends with a combinator" if
+        seen_step && pending_combinator != :descendant
+      raise Error, "empty selector" unless seen_step
+
+      xpath
+    end
+
+    def simple_selector_to_xpath(simple, combinator)
+      tag, preds = parse_simple(simple)
+
+      predicate = preds.empty? ? "" : "[#{preds.join(' and ')}]"
+
+      case combinator
+      when :adjacent
+        # The FIRST following sibling, constrained to the test +
+        # predicates (the CSS + semantics) — one combined
+        # predicate, which oga's XPath subset parses (chained
+        # [1][self::x] it does not).
+        combined = (["position() = 1", "name() = '#{tag}'"] +
+                    (preds.empty? ? [] : [preds.join(" and ")]))
+          .join(" and ")
+        "following-sibling::*[#{combined}]"
+      when :sibling
+        "following-sibling::#{tag}#{predicate}"
+      else
+        "#{tag}#{predicate}"
+      end
+    end
+
+    def parse_simple(simple)
+      tag = "*"
+      preds = []
+
+      simple.scan(SIMPLE_PART) do |tag_m, klass, id, pseudo, attr|
+        if tag_m
+          tag = tag_m
+        elsif klass
+          preds << "contains(concat(' ', normalize-space(@class), ' '), ' #{klass} ')"
+        elsif id
+          preds << "@id = '#{id}'"
+        elsif pseudo
+          preds << pseudo_predicate(pseudo)
+        elsif attr
+          preds << attr_predicate(attr)
+        end
+      end
+
+      [tag, preds]
+    end
+
+    def pseudo_predicate(pseudo)
+      case pseudo
+      when "first-child"
+        "count(preceding-sibling::*) = 0"
+      when "last-child"
+        "count(following-sibling::*) = 0"
+      when /\Anth-child\((\d+)\)\z/
+        "count(preceding-sibling::*) = #{Regexp.last_match(1).to_i - 1}"
+      when /\Anth-child\(odd\)\z/i
+        "count(preceding-sibling::*) mod 2 = 0"
+      when /\Anth-child\(even\)\z/i
+        "count(preceding-sibling::*) mod 2 = 1"
+      when /\Anot\((.+)\)\z/
+        inner = Regexp.last_match(1).strip
+        negate(inner)
+      else
+        raise Error, "unsupported pseudo :#{pseudo}"
+      end
+    end
+
+    def negate(inner_selector)
+      raise Error, ":not supports a single simple selector" if
+        inner_selector.match?(/[\s>+~,]/)
+
+      tag, preds = parse_simple(inner_selector)
+      return "false()" if tag == "*" && preds.empty?
+
+      checks = []
+      checks << "not(self::#{tag})" unless tag == "*"
+      checks.concat(preds.map { |p| "not(#{p})" })
+      "(#{checks.join(' and ')})"
+    end
+
+    def attr_predicate(expr)
+      # Linear string parsing — CodeQL rb/polynomial-redos flags
+      # the equivalent greedy regex (optional groups + .*\z
+      # backtrack polynomially on adversarial input).
+      expr = expr.strip
+      name = expr[/\A[\w:-]+/]
+      raise Error, "bad attribute selector: [#{expr}]" unless name
+
+      rest = expr[name.length..].to_s.strip
+      op = rest[/\A[~^$*|]?=/]
+      value = (op ? rest[op.length..] : "").to_s.strip
+      # No-backreference unquote (CodeQL rb/polynomial-redos: the
+      # ('(["']).*\1\z shape backtracks polynomially).
+      if value.length > 1 &&
+          ((value.start_with?("'") && value.end_with?("'")) ||
+           (value.start_with?('"') && value.end_with?('"')))
+        value = value[1..-2]
+      end
+      literal = xpath_string_literal(value)
+
+      case op
+      when nil, "" then "@#{name}"
+      when "=" then "@#{name} = #{literal}"
+      when "^=" then "starts-with(@#{name}, #{literal})"
+      when "$=" then "substring(@#{name}, string-length(@#{name}) - string-length(#{literal}) + 1) = #{literal}"
+      when "*=" then "contains(@#{name}, #{literal})"
+      when "~=" then "contains(concat(' ', normalize-space(@#{name}), ' '), concat(' ', #{literal}, ' '))"
+      when "|=" then "@#{name} = #{literal} or starts-with(@#{name}, concat(#{literal}, '-'))"
+      else raise Error, "unsupported attribute operator #{op}"
+      end
+    end
+
+    # An XPath 1.0 string literal: values containing apostrophes
+    # cannot escape the delimiter — they go through concat().
+    def xpath_string_literal(value)
+      return "'#{value}'" unless value.include?("'")
+
+      parts = value.split("'", -1).map { |seg| "'#{seg}'" }
+      "concat(#{parts.join(%(, "'", ))})"
+    end
+
+    def split_top_level(selector)
+      out = []
+      depth = 0
+      quote = nil
+      current = +""
+      selector.each_char do |c|
+        if quote
+          current << c
+          quote = nil if c == quote
+        elsif ["'", '"'].include?(c)
+          quote = c
+          current << c
+        elsif c == "["
+          depth += 1
+          current << c
+        elsif c == "]"
+          depth -= 1
+          raise Error, "unbalanced ]" if depth.negative?
+
+          current << c
+        elsif c == "," && depth.zero?
+          out << current
+          current = +""
+        else
+          current << c
+        end
+      end
+      raise Error, "unbalanced [" if depth.positive?
+
+      out << current
+      out.map(&:strip).reject(&:empty?)
+    end
+  end
+end

data/lib/moxml/node.rb

@@ -384,14 +384,25 @@ module Moxml
       xpath(expression, namespaces)
     end
 
-    def css(_expression)
-      raise Moxml::NotImplementedError,
-            "CSS selectors are not supported; use search with XPath"
+    # CSS through the shared Moxml::Css translator (#362.1): the
+    # SAME selector semantics on every adapter — the translation
+    # happens once, inside Moxml, so engines cannot diverge.
+    # NodeSet results document-order (the engines' native order).
+    def css(expression)
+      NodeSet.new(
+        adapter.xpath(@native, Css.to_xpath(expression,
+                                            absolute: document?)),
+        context,
+      )
     end
 
-    def at_css(_expression)
-      raise Moxml::NotImplementedError,
-            "CSS selectors are not supported; use at with XPath"
+    def at_css(expression)
+      Node.wrap(
+        adapter.at_xpath(@native,
+                         Css.to_xpath(expression,
+                                      absolute: document?)),
+        context,
+      )
     end
 
     def at_css_or_xpath(expression, namespaces = {})

data/lib/moxml/version.rb

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

data/lib/moxml/xsd.rb

@@ -19,14 +19,45 @@ module Moxml
   #       </xs:schema>
   #     XSD
   #     schema.valid?(doc)     # => true/false
-  #     schema.validate(doc)   # => [] or ["1:0: ...", ...]
+  #     schema.validate(doc)   # => [] or [ValidationError(...)]
   #
   # Adapters without an engine raise Moxml::NotImplementedError at
   # compile; Moxml::XSD.supported?(context) answers without
   # raising. The tier-1 scope is the engine's: documents outside it
   # validate laxly (see the binding's xsd_validate_spec).
   module XSD
-    SUPPORTED_ADAPTERS = %i[leptris].freeze
+    SUPPORTED_ADAPTERS = %i[leptris nokogiri].freeze
+
+    # One validation finding, harmonized across adapters (#362.2):
+    # +message+ always present; +line+ / +column+ when the engine
+    # reports them; +path+ (the element path) when the engine
+    # reports it — nil where the payload lacks the datum rather
+    # than a guessed placeholder. #to_s preserves the plain-string
+    # consumer flows the pre-#362 string contract fed.
+    class ValidationError
+      attr_reader :message, :line, :column, :path
+
+      def initialize(message:, line: nil, column: nil, path: nil)
+        @message = message.to_s
+        @line = line
+        @column = column
+        @path = path
+      end
+
+      def to_s
+        if line
+          "#{line}: #{message}"
+        else
+          message
+        end
+      end
+
+      def ==(other)
+        other.is_a?(ValidationError) &&
+          message == other.message && line == other.line &&
+          column == other.column && path == other.path
+      end
+    end
 
     class << self
       # Whether the context's adapter ships an XSD validator.
@@ -51,6 +82,13 @@ module Moxml
     # A compiled schema (adapter-owned handle). Validation results
     # are the engine's accumulated messages; [] means valid.
     class Schema
+      def check_released!
+        return unless released?
+
+        raise Moxml::AdapterError,
+              "schema released (deterministic drop); compile a new one"
+      end
+
       def initialize(handle, context)
         @handle = handle
         @context = context
@@ -65,6 +103,7 @@ module Moxml
       # visible); pass a Moxml::Document to control the parse
       # yourself.
       def validate(node_or_xml)
+        check_released!
         doc = case node_or_xml
               when Moxml::Document then node_or_xml
               when Moxml::Node then node_or_xml.document
@@ -85,18 +124,35 @@ module Moxml
       end
 
       def valid?(node_or_xml)
+        check_released!
         validate(node_or_xml).empty?
       end
 
       # Number of top-level schema declarations the compiler
       # recognized.
       def declarations
+        check_released!
         @context.config.adapter.xsd_declarations(@handle)
       end
 
+      # Deterministic drop (#362.3): true when the adapter freed
+      # the engine-side schema NOW; false when the adapter can only
+      # wait for GC (documented per adapter). After a true release
+      # the faces raise AdapterError — the handle is gone.
+      def release
+        dropped = @context.config.adapter.xsd_release(@handle)
+        @released = true if dropped
+        dropped
+      end
+
+      def released?
+        @released == true
+      end
+
       # The engine's schema-level compile error, or nil when the
       # schema compiled cleanly.
       def compile_error
+        check_released!
         @context.config.adapter.xsd_compile_error(@handle)
       end
 

data/lib/moxml.rb

@@ -84,6 +84,7 @@ module Moxml
   autoload :EntityReference, "moxml/entity_reference"
   autoload :DocumentBuilder, "moxml/document_builder"
   autoload :HtmlFragment, "moxml/html_fragment"
+  autoload :Css, "moxml/css"
   autoload :Builder, "moxml/builder"
   autoload :Entity, "moxml/entity"
   autoload :EntityRegistry, "moxml/entity_registry"

data/spec/moxml/css_spec.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# #362.1: CSS selection through the shared Moxml::Css translator —
+# one implementation for every adapter, so selector semantics
+# converge by construction. The correctness oracle is
+# nokogiri-native CSS: the translated XPath must return the same
+# node sets for the corpus.
+RSpec.describe "Moxml CSS selection (#362.1)" do
+  let(:source) do
+    <<~HTML
+      <doc>
+        <p id="first" class="lead intro">one</p>
+        <p class="lead">two <b>bold</b></p>
+        <div class="wrap">
+          <p data-k="v">three</p>
+          <span>four</span>
+          <p>five</p>
+        </div>
+        <section><article>deep</article></section>
+      </doc>
+    HTML
+  end
+
+  describe "Moxml::Css.to_xpath" do
+    def xp(sel, absolute: false)
+      Moxml::Css.to_xpath(sel, absolute: absolute)
+    end
+
+    it "translates the core shapes" do
+      expect(xp("p", absolute: true)).to eq("//p")
+      expect(xp(".lead", absolute: true))
+        .to include("contains(concat(' ', normalize-space(@class)")
+      expect(xp("#first", absolute: true)).to eq("//*[@id = 'first']")
+      expect(xp("[data-k]", absolute: true)).to eq("//p/*[@data-k]").or include("[@data-k]")
+      expect(xp("div > p", absolute: true)).to eq("//div/p")
+      expect(xp("div p", absolute: true)).to eq("//div//p")
+      expect(xp("span + p", absolute: true))
+        .to eq("//span/following-sibling::*[position() = 1 and name() = 'p']")
+      expect(xp("p ~ span", absolute: true))
+        .to eq("//p/following-sibling::span")
+    end
+
+    it "supports attribute operators" do
+      expect(xp("[href^='h']", absolute: true))
+        .to include("starts-with(@href, 'h')")
+      expect(xp("[href$='z']", absolute: true)).to include("substring(@href")
+      expect(xp("[href*='mid']", absolute: true)).to include("contains(@href, 'mid')")
+      expect(xp("[lang|=en]", absolute: true))
+        .to include("starts-with(@lang, concat('en', '-')")
+    end
+
+    it "supports positional pseudos" do
+      expect(xp("p:first-child", absolute: true))
+        .to include("count(preceding-sibling::*) = 0")
+      expect(xp("p:nth-child(3)", absolute: true))
+        .to include("count(preceding-sibling::*) = 2")
+      expect(xp("p:nth-child(odd)", absolute: true))
+        .to include("mod 2 = 0")
+    end
+
+    it "negates simple selectors with :not" do
+      expect(xp("p:not(.lead)", absolute: true))
+        .to include("not(contains(")
+      expect(xp(":not(p)", absolute: true)).to include("not(self::p)")
+    end
+
+    it "groups comma selectors into a union" do
+      expect(xp("div, section", absolute: true)).to include(" | ")
+    end
+
+    it "raises Css::Error on unsupported shapes" do
+      expect { xp("p:hover") }.to raise_error(Moxml::Css::Error, /pseudo/)
+      expect { xp("> p") }.to raise_error(Moxml::Css::Error)
+      expect { xp("p >>") }.to raise_error(Moxml::Css::Error)
+      expect { xp("") }.to raise_error(Moxml::Css::Error)
+    end
+  end
+
+  describe "Node#css / at_css" do
+    let(:expected) do
+      {
+        "p" => 4, "#first" => 1, ".lead" => 2, "p.lead" => 2,
+        "div p" => 2, "div > p" => 2, "[data-k]" => 1,
+        "[data-k=v]" => 1, "p:not(.lead)" => 2,
+        "p:first-child" => 2, "p:nth-child(3)" => 1,
+        "section article" => 1, "div, section" => 2,
+        "span + p" => 1, "p ~ span" => 1
+      }
+    end
+
+    %i[nokogiri leptris oga ox rexml].each do |adapter_name|
+      describe "on #{adapter_name}" do
+        let(:ctx) { Moxml.new(adapter_name) }
+        let(:doc) { ctx.parse(source) }
+
+        it "returns the nokogiri-native CSS node sets" do
+          expected.each do |sel, want|
+            expect(doc.css(sel).size).to eq(want),
+                                         "#{sel} => #{doc.css(sel).size}, want #{want}"
+          end
+        end
+
+        it "at_css returns the first match" do
+          expect(doc.at_css("p").text).to eq("one")
+          expect(doc.at_css("div p").text).to eq("three")
+          expect(doc.at_css("nosuch")).to be_nil
+        end
+      end
+    end
+
+    it "scopes element-subtree selection" do
+      ctx = Moxml.new(:leptris)
+      doc = ctx.parse(source)
+      wrap = doc.at_css("div")
+      expect(wrap.css("p").size).to eq(2)
+      expect(doc.at_css("doc").css("section article").size).to eq(1)
+    end
+  end
+end

data/spec/moxml/xsd_error_contract_spec.rb

@@ -0,0 +1,72 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# #362.2: Schema#validate returns one error shape on every
+# adapter — Moxml::XSD::ValidationError(message:, line:, column:,
+# path:) — so consumers present findings uniformly. Each adapter
+# fills what its engine reports; missing data is nil, never a
+# guessed placeholder.
+RSpec.describe "Moxml::XSD::ValidationError contract (#362.2)" do
+  let(:schema_text) do
+    <<~XSD
+      <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
+        <xs:element name="r">
+          <xs:complexType>
+            <xs:sequence>
+              <xs:element name="a"/>
+              <xs:element name="b"/>
+            </xs:sequence>
+          </xs:complexType>
+        </xs:element>
+      </xs:schema>
+    XSD
+  end
+  let(:bad_doc) { "<r><a/></r>" }
+
+  %i[nokogiri leptris].each do |adapter_name|
+    describe "on #{adapter_name}" do
+      let(:ctx) { Moxml.new(adapter_name) }
+      let(:schema) { ctx.xsd(schema_text) }
+      let(:errors) { schema.validate(ctx.parse(bad_doc)) }
+
+      it "returns the structured contract" do
+        expect(errors).not_to be_empty
+        expect(errors).to all(be_a(Moxml::XSD::ValidationError))
+        expect(errors.first.message).not_to be_empty
+      end
+
+      it "to_s preserves plain-string flows" do
+        expect(errors.map(&:to_s)).to all(be_a(String))
+      end
+    end
+  end
+
+  describe "adapter payloads" do
+    it "nokogiri carries the line (libxml2 structured errors)" do
+      ctx = Moxml.new(:nokogiri)
+      errors = ctx.xsd(schema_text).validate(ctx.parse(bad_doc))
+      expect(errors.first.line).to eq(1)
+    end
+
+    it "leptris reports message only (line/path ride leptris-ruby#419)" do
+      ctx = Moxml.new(:leptris)
+      errors = ctx.xsd(schema_text).validate(ctx.parse(bad_doc))
+      expect(errors.first.line).to be_nil
+      expect(errors.first.path).to be_nil
+    end
+  end
+
+  describe "the ValidationError object" do
+    it "compares fieldwise and formats with the line" do
+      a = Moxml::XSD::ValidationError.new(message: "boom", line: 3)
+      b = Moxml::XSD::ValidationError.new(message: "boom", line: 3)
+      c = Moxml::XSD::ValidationError.new(message: "other", line: 3)
+      expect(a).to eq(b)
+      expect(a).not_to eq(c)
+      expect(a.to_s).to eq("3: boom")
+      expect(Moxml::XSD::ValidationError.new(message: "bare").to_s)
+        .to eq("bare")
+    end
+  end
+end

data/spec/moxml/xsd_release_spec.rb

@@ -0,0 +1,76 @@
+# frozen_string_literal: true
+
+require "spec_helper"
+
+# #362.3: Schema#release — deterministic drop where the engine
+# supports it, an explicit no-op-with-false where it cannot, and
+# a documented contract for long-lived validation services.
+RSpec.describe "Moxml::XSD::Schema#release (#362.3)" do
+  let(:schema_text) do
+    <<~XSD
+      <xs:schema xmlns:xs="http://www.w3.org/2001/XMLSchema">
+        <xs:element name="a" type="xs:string"/>
+      </xs:schema>
+    XSD
+  end
+
+  describe "on leptris" do
+    let(:ctx) { Moxml.new(:leptris) }
+
+    context "with the release ride armed (binding >= 1.9.342.0)" do
+      before do
+        unless Moxml::Adapter::Leptris::XSD_RELEASE
+          skip "binding #{Leptris::VERSION} predates Schema#release"
+        end
+      end
+
+      it "drops the engine schema deterministically" do
+        schema = ctx.xsd(schema_text)
+        expect(schema.valid?(ctx.parse("<a/>"))).to be(true)
+        expect(schema.release).to be(true)
+        expect(schema.released?).to be(true)
+      end
+
+      it "raises on faces after release" do
+        schema = ctx.xsd(schema_text)
+        schema.release
+        expect { schema.valid?(ctx.parse("<a/>")) }
+          .to raise_error(Moxml::AdapterError, /released/)
+        expect { schema.declarations }
+          .to raise_error(Moxml::AdapterError, /released/)
+      end
+
+      it "frees without a double free at GC" do
+        schema = ctx.xsd(schema_text)
+        schema.release
+        GC.start
+        expect(schema.released?).to be(true)
+      end
+    end
+
+    context "when the binding predates the ride" do
+      before do
+        if Moxml::Adapter::Leptris::XSD_RELEASE
+          skip "binding #{Leptris::VERSION} carries Schema#release"
+        end
+      end
+
+      it "answers false (GC-only) and keeps the schema usable" do
+        schema = ctx.xsd(schema_text)
+        expect(schema.release).to be(false)
+        expect(schema).not_to be_released
+        expect(schema.valid?(ctx.parse("<a/>"))).to be(true)
+      end
+    end
+  end
+
+  describe "on nokogiri" do
+    it "answers false — libxml2 frees at GC, documented" do
+      ctx = Moxml.new(:nokogiri)
+      schema = ctx.xsd(schema_text)
+      expect(schema.release).to be(false)
+      expect(schema).not_to be_released
+      expect(schema.valid?(ctx.parse("<a/>"))).to be(true)
+    end
+  end
+end

data/spec/moxml/xsd_spec.rb

@@ -123,11 +123,14 @@ RSpec.describe Moxml::XSD do
       expect(schema.instance_variable_get(:@parsed_source)).to be_nil
     end
 
-    it "normalizes validate entries to strings (moxml contract)" do
+    it "normalizes validate entries to the #362.2 ValidationError contract" do
       schema = ctx.xsd(schema_text)
       errors = schema.validate("<note><wrong/></note>")
       expect(errors).not_to be_empty
-      expect(errors).to all(be_a(String))
+      expect(errors).to all(be_a(Moxml::XSD::ValidationError))
+      # to_s preserves the plain-string consumer flows.
+      expect(errors.map(&:to_s)).to all(be_a(String))
+      expect(errors.first.message).not_to be_empty
     end
 
     it "derives XSD_SUPPORTED from the engine face gate" do

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: moxml
 version: !ruby/object:Gem::Version
-  version: 0.5.127
+  version: 0.5.128
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-11 00:00:00.000000000 Z
+date: 2026-10-12 00:00:00.000000000 Z
 dependencies: []
 description: |
   Moxml is a unified XML manipulation library that provides a common API
@@ -202,6 +202,7 @@ files:
 - lib/moxml/comment.rb
 - lib/moxml/config.rb
 - lib/moxml/context.rb
+- lib/moxml/css.rb
 - lib/moxml/declaration.rb
 - lib/moxml/doctype.rb
 - lib/moxml/document.rb
@@ -487,6 +488,7 @@ files:
 - spec/moxml/comment_spec.rb
 - spec/moxml/config_spec.rb
 - spec/moxml/context_spec.rb
+- spec/moxml/css_spec.rb
 - spec/moxml/cycle_rejection_spec.rb
 - spec/moxml/declaration_preservation_spec.rb
 - spec/moxml/declaration_spec.rb
@@ -575,6 +577,8 @@ files:
 - spec/moxml/xpath/union_spec.rb
 - spec/moxml/xpath_capabilities_spec.rb
 - spec/moxml/xpath_spec.rb
+- spec/moxml/xsd_error_contract_spec.rb
+- spec/moxml/xsd_release_spec.rb
 - spec/moxml/xsd_spec.rb
 - spec/moxml/xslt/stylesheet_spec.rb
 - spec/performance/README.md