moxml-testsuite 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: c83c47e9b732b9b23aa8923894275f0b5e9820c050b56363a1713a4305bd0d77
+  data.tar.gz: 56443d6aaae65d2934e47c96903551ca474270bf5682cd23214e52908c1e6350
+SHA512:
+  metadata.gz: 9b921670e6cd7d478782efd840b11167ff9c9130a39635313fea482383569606c3a108ebe7be19f1edcd69de9930e7e2ba61ecd29460af0fb3fbe30d646bf865
+  data.tar.gz: cf51812479aa486ae07c7ce65fa1407833ec1ac1c294c558a59997d72cc2b6f9cf5d89bf9fe2c36ab8f25c7a9588cac105af6bda9d8fb861c96994c131c34701

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Ribose Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.adoc

@@ -0,0 +1,60 @@
+= moxml-testsuite
+
+image:https://img.shields.io/gem/v/moxml-testsuite.svg["Gem Version", link="https://rubygems.org/gems/moxml-testsuite"]
+
+The moxml conformance test suite: certify any XML engine against the moxml model.
+
+The moxml processing model (https://github.com/lutaml/moxml — `docs/_references/processing-model.adoc`) is a set of committed answers: one object model, one document order, one serialization shape, one canonicalization, one validation verdict — for every question an XML program can ask. The moxml conformance dataset (schema 5, 177 cases across seven families) IS those answers as data, and this gem is the runner that drives any engine through them.
+
+== The seven families
+
+[cols="1,2,3"]
+|===
+|Family |Cases |Facade faces
+
+|builtin_lexical |81 |`lexical_valid?(type_name, lexical)`
+|xsd_regex_translation |21 |`regex_translates?(pattern)`
+|schema_wildcards |24 |`wildcard_covers?(...)`, `wildcard_exclusion?(...)`
+|entity_registry |11 |`entity_declared?(...)` and the registry faces
+|serialization |20 |`parse(xml)`, `serialize(doc)`
+|c14n |14 |`canonicalize(doc)`
+|xsd_structural |6 |`validate_xsd(schema, instance)`
+|===
+
+== Certifying an engine
+
+The dataset ships vendored (`testdata/moxml-conformance.json`); the runner consumes rows and never restates them. Any object implementing the certification protocol can be certified:
+
+[source, ruby]
+----
+require "moxml/testsuite"
+
+report = Moxml::TestSuite.run(Moxml::TestSuite::Reference.new)
+puts report
+report.passed? # => true
+----
+
+`Reference` implements the whole protocol on moxml itself — pin the engine when the host carries several:
+
+[source, ruby]
+----
+Moxml::TestSuite::Reference.new(adapter: :leptris)
+Moxml::TestSuite::Reference.new(adapter: :nokogiri)
+----
+
+A facade that cannot answer a family's faces sees that family SKIP — loudly, in the report — never a quiet pass. A facade that answers against the dataset FAILs with the offending case named.
+
+== The one-directional contract
+
+The model's degradation is one-directional: an engine that cannot evaluate a construct stays silent (under-report); it never produces a different answer. The suite pins that too — unevaluatable rows expect under-reporting, and "answered wrong" and "answered differently per engine" are both failures. Equivalence is to the model, not merely engine-to-engine.
+
+== Provenance
+
+The dataset is generated from the moxml suite (`rake conformance:export` in lutaml/moxml) and consumed by the cross-language runners: moxml-rs (Rust) and moxml-ts (TypeScript). schema 5 is the row-shape version; `generator` names the producing moxml release.
+
+== Development
+
+----
+bundle install
+bundle exec rake
+----

data/lib/moxml/testsuite/dataset.rb

@@ -0,0 +1,43 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Moxml
+  module TestSuite
+    # The vendored dataset: the model's committed answers, seven
+    # families, schema-versioned. The JSON is the single source -
+    # runners consume rows, never restate them.
+    module Dataset
+      FAMILIES = %w[
+        builtin_lexical
+        xsd_regex_translation
+        schema_wildcards
+        entity_registry
+        serialization
+        c14n
+        xsd_structural
+      ].freeze
+
+      DATA_PATH = File.join(__dir__, "../../../testdata/moxml-conformance.json")
+
+      def self.load(path: DATA_PATH)
+        raw = JSON.parse(File.read(path))
+        Dataset::V1.new(raw)
+      end
+
+      class V1
+        attr_reader :schema, :generator, :cases
+
+        def initialize(raw)
+          @schema = raw["schema"]
+          @generator = raw["generator"]
+          @cases = raw["cases"]
+        end
+
+        def rows(family)
+          @cases.fetch(family)
+        end
+      end
+    end
+  end
+end

data/lib/moxml/testsuite/families/c14n.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Moxml
+  module TestSuite
+    module Families
+      # Family: c14n (14 rows). Canonical XML 1.0, byte-identical:
+      # sorted attributes, expanded references, comments dropped.
+      # Facade: parse(xml) -> doc; canonicalize(doc) -> string.
+      class C14n
+        def initialize(facade, dataset)
+          @facade = facade
+          @rows = dataset.rows("c14n")
+        end
+
+        def call(report)
+          unless @facade.respond_to?(:canonicalize)
+            return report.skip("c14n", "facade does not implement canonicalize")
+          end
+
+          failures = []
+          @rows.each do |row|
+            doc = @facade.parse(row["input"])
+            out = @facade.canonicalize(doc)
+            if out != row["canonical"]
+              failures << format("%s: got %s, want %s",
+                                 row["id"], out.inspect,
+                                 row["canonical"].inspect)
+            end
+          rescue StandardError => e
+            failures << format("%s: raised %s: %s", row["id"], e.class,
+                               e.message[0, 120])
+          end
+          if failures.empty?
+            report.pass("c14n", @rows.length)
+          else
+            report.fail("c14n", failures, @rows.length)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/moxml/testsuite/families/decisions.rb

@@ -0,0 +1,120 @@
+# frozen_string_literal: true
+
+module Moxml
+  module TestSuite
+    module Families
+      # Families: the pure-logic decision faces (the model's
+      # committed answers as functions).
+      #
+      # builtin_lexical (81): lexical_valid?(type_name, lexical)
+      # schema_wildcards (24): the pinned covers/exclusion protocol -
+      #   wildcard_covers?(constraint:, process:, not_namespace:,
+      #                    not_qname:, item_namespace:) -> bool
+      #   wildcard_exclusion?(constraint:, process:, not_namespace:,
+      #                       not_qname:, item_namespace:, item_name:,
+      #                       defined:, sibling_names:) -> String | nil
+      #   (the dataset's committed shape: a row answers covers? plus
+      #   the negative-exclusion symbol; there is no single "admits")
+      # xsd_regex_translation (21): regex_translates?(pattern) ->
+      #   regexp | nil (nil = untranslatable per the model).
+      class Decisions
+        def initialize(facade, dataset)
+          @facade = facade
+          @dataset = dataset
+        end
+
+        DECISION_FACES = %i[
+          lexical_valid? wildcard_covers? regex_translates?
+        ].freeze
+
+        def call(report)
+          if DECISION_FACES.none? { |face| @facade.respond_to?(face) }
+            return report.skip("decisions",
+                               "facade does not implement the decision faces")
+          end
+
+          failures = []
+          failures += run_lexical
+          failures += run_wildcards
+          failures += run_regex
+          total = @dataset.rows("builtin_lexical").length +
+            @dataset.rows("schema_wildcards").length +
+            @dataset.rows("xsd_regex_translation").length
+          if failures.empty?
+            report.pass("decisions", total)
+          else
+            report.fail("decisions", failures, total)
+          end
+        end
+
+        private
+
+        def run_lexical
+          return [] unless @facade.respond_to?(:lexical_valid?)
+
+          @dataset.rows("builtin_lexical").filter_map do |row|
+            next if @facade.lexical_valid?(row["type"],
+                                           row["lexical"]) == row["valid"]
+
+            format("lexical %s %s: got %s, want %s",
+                   row["type"], row["lexical"].inspect,
+                   !row["valid"], row["valid"])
+          end
+        rescue NoMethodError, ArgumentError => e
+          ["lexical face unavailable: #{e.class}: #{e.message[0, 80]}"]
+        end
+
+        def run_wildcards
+          return [] unless @facade.respond_to?(:wildcard_covers?)
+
+          @dataset.rows("schema_wildcards").filter_map do |row|
+            common = {
+              constraint: row["constraint"], process: row["process"],
+              not_namespace: row["not_namespace"],
+              not_qname: Array(row["not_qname"]),
+              item_namespace: row["item_namespace"]
+            }
+            covers = @facade.wildcard_covers?(**common)
+            unless covers == row["covers"]
+              next format("wildcard %s/%s covers?(%s): got %s, want %s",
+                          row["constraint"], row["process"],
+                          row["item_qname"], covers, row["covers"])
+            end
+
+            exclusion = @facade.wildcard_exclusion?(
+              **common, item_name: row["item_qname"],
+                        defined: row["defined"],
+                        sibling_names: Array(row["sibling_names"])
+            )
+            want = row["exclusion"]
+            next if exclusion.to_s == want.to_s
+
+            format("wildcard %s/%s exclusion(%s): got %s, want %s",
+                   row["constraint"], row["process"], row["item_qname"],
+                   exclusion.inspect, want.inspect)
+          end
+        rescue NoMethodError, ArgumentError => e
+          ["wildcard face unavailable: #{e.class}: #{e.message[0, 80]}"]
+        end
+
+        def run_regex
+          return [] unless @facade.respond_to?(:regex_translates?)
+
+          @dataset.rows("xsd_regex_translation").filter_map do |row|
+            compiled = @facade.regex_translates?(row["pattern"])
+            next if compiled.nil? != row["translatable"]
+
+            next unless row["translatable"] &&
+              compiled.match?(row["value"]) != row["matches"]
+
+            format("regex %s %s: matched %s, want %s",
+                   row["pattern"].inspect, row["value"].inspect,
+                   compiled.match?(row["value"]), row["matches"])
+          end
+        rescue NoMethodError, ArgumentError => e
+          ["regex face unavailable: #{e.class}: #{e.message[0, 80]}"]
+        end
+      end
+    end
+  end
+end

data/lib/moxml/testsuite/families/entity_registry.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module Moxml
+  module TestSuite
+    module Families
+      # Family: entity_registry (11 rows). The registry contract:
+      # lookup (declared?, codepoint_for_name, names_for_codepoint,
+      # primary_name_for_codepoint, standard_entity?) and restoration
+      # (should_restore? under a restoration mode). Facade faces are
+      # seed-scoped - every call carries the seed map so engines stay
+      # stateless across rows:
+      #
+      #   entity_declared?(seed:, name:)
+      #   entity_codepoint(seed:, name:)
+      #   entity_names(seed:, codepoint:)
+      #   entity_primary_name(seed:, codepoint:)
+      #   entity_standard?(seed:, codepoint:)
+      #   entity_should_restore?(seed:, codepoint:, restore_entities:,
+      #                          restoration_mode:)
+      class EntityRegistry
+        def initialize(facade, dataset)
+          @facade = facade
+          @rows = dataset.rows("entity_registry")
+        end
+
+        def call(report)
+          unless @facade.respond_to?(:entity_declared?)
+            return report.skip("entity_registry",
+                               "facade does not implement the registry faces")
+          end
+
+          failures = []
+          @rows.each do |row|
+            failures.concat(check_row(row))
+          end
+          if failures.empty?
+            report.pass("entity_registry", @rows.length)
+          else
+            report.fail("entity_registry", failures,
+                        @rows.length)
+          end
+        end
+
+        private
+
+        def check_row(row)
+          seed = row["seed"]
+          label = "#{row['qname'].inspect}/#{row['qcp']} seed=#{seed.inspect}"
+          [
+            [row["declared"],
+             @facade.entity_declared?(seed: seed, name: row["qname"])],
+            [row["codepoint"],
+             @facade.entity_codepoint(seed: seed, name: row["qname"])],
+            [row["names"],
+             @facade.entity_names(seed: seed, codepoint: row["qcp"])],
+            [row["primary"],
+             @facade.entity_primary_name(seed: seed, codepoint: row["qcp"])],
+            [row["standard"],
+             @facade.entity_standard?(seed: seed, codepoint: row["qcp"])],
+            [row["restore"],
+             @facade.entity_should_restore?(
+               seed: seed, codepoint: row["qcp"],
+               restore_entities: row["restore_entities"],
+               restoration_mode: row["mode"]
+             )],
+          ].filter_map do |want, got|
+            next if want == got
+
+            format("%s: got %s, want %s", label, got.inspect, want.inspect)
+          end
+        rescue StandardError => e
+          [format("%s: raised %s: %s", label, e.class, e.message[0, 120])]
+        end
+      end
+    end
+  end
+end

data/lib/moxml/testsuite/families/serialization.rb

@@ -0,0 +1,40 @@
+# frozen_string_literal: true
+
+module Moxml
+  module TestSuite
+    module Families
+      # Family: serialization (20 rows). The emitter contract:
+      # long-form empty elements, the attribute escaping shapes
+      # (named + numeric references), namespace declarations
+      # verbatim. Facade: parse(xml) -> doc; serialize(doc) -> string.
+      class Serialization
+        def initialize(facade, dataset)
+          @facade = facade
+          @rows = dataset.rows("serialization")
+        end
+
+        def call(report)
+          failures = []
+          @rows.each do |row|
+            doc = @facade.parse(row["input"])
+            out = @facade.serialize(doc)
+            # A single trailing document newline is formatting, not a
+            # committed emitter shape - the dataset rows are chomped.
+            if out&.chomp != row["output"]
+              failures << format("%s: got %s, want %s",
+                                 row["id"], out.inspect, row["output"].inspect)
+            end
+          rescue StandardError => e
+            failures << format("%s: raised %s: %s", row["id"], e.class,
+                               e.message[0, 120])
+          end
+          if failures.empty?
+            report.pass("serialization", @rows.length)
+          else
+            report.fail("serialization", failures, @rows.length)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/moxml/testsuite/families/xsd_structural.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+module Moxml
+  module TestSuite
+    module Families
+      # Family: xsd_structural (6 rows). Schema + instance pairs
+      # with the committed verdict. Facade: parse(xml);
+      # validate_xsd(schema_xml, instance) -> [] (valid) | [#to_s].
+      class XsdStructural
+        def initialize(facade, dataset)
+          @facade = facade
+          @rows = dataset.rows("xsd_structural")
+        end
+
+        def call(report)
+          unless @facade.respond_to?(:validate_xsd)
+            return report.skip("xsd_structural",
+                               "facade does not implement validate_xsd")
+          end
+
+          failures = []
+          @rows.each do |row|
+            errs = @facade.validate_xsd(row["schema"], row["instance"])
+            valid = errs.nil? || errs.empty?
+            expected = row["valid"]
+            if valid != expected
+              failures << format("%s: expected %s, engine said %s (%s)",
+                                 row["id"], expected, valid,
+                                 Array(errs).first || "no rows")
+            end
+          rescue StandardError => e
+            failures << format("%s: raised %s: %s", row["id"], e.class,
+                               e.message[0, 120])
+          end
+          if failures.empty?
+            report.pass("xsd_structural", @rows.length)
+          else
+            report.fail("xsd_structural", failures,
+                        @rows.length)
+          end
+        end
+      end
+    end
+  end
+end

data/lib/moxml/testsuite/reference.rb

@@ -0,0 +1,129 @@
+# frozen_string_literal: true
+
+module Moxml
+  module TestSuite
+    # The moxml-backed reference facade: every certification face
+    # answered through moxml itself. Any moxml install certifies its
+    # own engine with it:
+    #
+    #   report = Moxml::TestSuite.run(Moxml::TestSuite::Reference.new)
+    #   puts report
+    #   report.passed? # => true
+    #
+    # Pin the engine explicitly when the host carries several:
+    #
+    #   Moxml::TestSuite::Reference.new(adapter: :leptris)
+    #
+    # The decision faces (lexical, wildcard, regex, entity registry)
+    # are engine-free - moxml answers them in pure Ruby, the model's
+    # committed answers. The DOM faces (parse, serialize, canonicalize,
+    # validate_xsd) run on the selected adapter: that is the point -
+    # the suite certifies the ENGINE's observable behavior against
+    # the model.
+    class Reference
+      def initialize(adapter: nil)
+        require "moxml"
+        @context = adapter ? Moxml.new(adapter) : Moxml.new
+        # The dataset pins the model's committed emitter shape:
+        # compact, no inter-element indentation.
+        @context.config.default_indent = 0
+      end
+
+      attr_reader :context
+
+      # -- DOM faces -------------------------------------------------
+
+      def parse(xml)
+        @context.parse(xml)
+      end
+
+      def serialize(doc)
+        doc.to_xml
+      end
+
+      def canonicalize(doc)
+        Moxml::C14n.canonicalize(doc)
+      end
+
+      def validate_xsd(schema_xml, instance)
+        @context.xsd(schema_xml).validate(instance)
+      end
+
+      # -- decision faces (engine-free) ------------------------------
+
+      def lexical_valid?(type_name, lexical)
+        Moxml::XSD::BuiltinLexical.valid?(type_name, lexical)
+      end
+
+      def regex_translates?(pattern)
+        Moxml::XSD::SchemaRules::XsdRegex.translate(pattern)
+      end
+
+      def wildcard_covers?(constraint:, process:, not_namespace:,
+                           not_qname:, item_namespace:)
+        wildcard(constraint, process, not_namespace, not_qname)
+          .covers?(item_namespace.to_sym)
+      end
+
+      def wildcard_exclusion?(constraint:, process:, not_namespace:,
+                              not_qname:, item_namespace:, item_name:,
+                              defined:, sibling_names:)
+        answer = wildcard(constraint, process, not_namespace, not_qname)
+          .negative_exclusion(item_name, item_namespace.to_sym,
+                              defined: defined,
+                              sibling_names: sibling_names)
+        answer&.to_s
+      end
+
+      def entity_declared?(seed:, name:)
+        registry(seed).declared?(name)
+      end
+
+      def entity_codepoint(seed:, name:)
+        registry(seed).codepoint_for_name(name)
+      end
+
+      def entity_names(seed:, codepoint:)
+        registry(seed).names_for_codepoint(codepoint)
+      end
+
+      def entity_primary_name(seed:, codepoint:)
+        registry(seed).primary_name_for_codepoint(codepoint)
+      end
+
+      def entity_standard?(seed:, codepoint:)
+        registry(seed).standard_entity?(codepoint)
+      end
+
+      def entity_should_restore?(seed:, codepoint:, restore_entities:,
+                                 restoration_mode:)
+        registry(seed).should_restore?(
+          codepoint, config: restoration_config(restore_entities,
+                                                restoration_mode)
+        )
+      end
+
+      private
+
+      def wildcard(constraint, process, not_namespace, not_qname)
+        Moxml::XSD::SchemaRules::Wildcard.new(
+          constraint, process,
+          not_namespace: not_namespace,
+          not_qname: Array(not_qname).join(" "),
+          element: nil
+        )
+      end
+
+      def registry(seed)
+        Moxml::EntityRegistry.new(mode: :custom, entity_provider: -> { seed })
+      end
+
+      def restoration_config(restore_entities, restoration_mode)
+        config = Moxml::Config.new
+        config.restore_entities = restore_entities
+        config.entity_restoration_mode = restoration_mode.to_sym
+        config
+      end
+    end
+  end
+end

data/lib/moxml/testsuite/report.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+module Moxml
+  module TestSuite
+    # The certification outcome: per-family pass/fail/skip with the
+    # failing case ids. Truthy: report.passed? after run.
+    class Report
+      attr_reader :facade_class, :results
+
+      def initialize(facade_class:)
+        @facade_class = facade_class
+        @results = {}
+      end
+
+      def pass(family, count)
+        @results[family] = { status: :pass, count: count, failures: [] }
+      end
+
+      def fail(family, failures, count)
+        @results[family] = { status: :fail, count: count, failures: failures }
+      end
+
+      def skip(family, reason)
+        @results[family] = { status: :skip, reason: reason }
+      end
+
+      def passed?
+        @results.values.all? { |r| r[:status] != :fail }
+      end
+
+      def failures
+        @results.select { |_, r| r[:status] == :fail }
+      end
+
+      def summary
+        lines = ["moxml-testsuite (facade: #{@facade_class})"]
+        @results.each do |family, r|
+          case r[:status]
+          when :pass then lines << "  PASS #{family} (#{r[:count]} cases)"
+          when :fail
+            lines << "  FAIL #{family} " \
+                     "(#{r[:failures].length}/#{r[:count]} cases):"
+            r[:failures].each { |f| lines << "       #{f}" }
+          when :skip then lines << "  SKIP #{family} (#{r[:reason]})"
+          end
+        end
+        lines.join("\n")
+      end
+
+      def to_s
+        summary
+      end
+    end
+  end
+end

data/lib/moxml/testsuite/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Moxml
+  module TestSuite
+    VERSION = "0.1.0"
+  end
+end