canon 0.3.115 → 0.3.116

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: f0837e14a667e91da2ce1818ecab8ca194f7ab1353ac8db3703ba6bee4ea6857
-  data.tar.gz: 4a9345754f64e4cae207ee7285ab0bc88b8aa5747090897aa479f9b30cf07f45
+  metadata.gz: 89df5f303938b98100a1d44399c7eb5fbbf793f0f91c445c4f0533a19234d5ec
+  data.tar.gz: 1308c9228b0a6efc15e81ebef134c7495aadd100e10978a23ee09b92ad558555
 SHA512:
-  metadata.gz: 6524509bb0f1c3aa27b419c45959fee9eb84c38c44859373f0d926cb729bb0796cf59cc4fe12567cd2480090bbc6dad640ca759e166cbd6e629c38e254d20832
-  data.tar.gz: 01fb13b4b41701f57127324a0f667c721a7a55121a08e64eae8ac291595a0596544916daf274e62da30de07a4f2b1153f2f73afa76d63c1f5fca31751763a1a7
+  metadata.gz: 93cfb6bca734697c5cc79173dac20bbe53cb4fb17e72fc72e7aa726af366c187c09ae0c30e5a775d9ea8b9e94f1194b29657f9da3d44c58f6fbc116717e39909
+  data.tar.gz: 37f713fb17fe7961cb622f42c96605cf0bb19227a6831018d0505afdc33ad2e315e54b1a65145219457e30d8b0c6d06d001869611bbe94f55b443c2cbf0e4252

data/lib/canon/comparison/schema_gate.rb

@@ -0,0 +1,29 @@
+# frozen_string_literal: true
+
+module Canon
+  module Comparison
+    # W5.1 validate-then-compare: runs both documents through the
+    # engine's XSD assessment before the diff. Returns a hash of
+    # side-index (0 or 1) to Canon::ValidationError — empty when both
+    # documents pass and the comparison may proceed.
+    module SchemaGate
+      module_function
+
+      # @param obj1 [String] first XML document
+      # @param obj2 [String] second XML document
+      # @param schema [String, Leptris::XML::XSD::Schema] schema text
+      #   (compiled once here) or a compiled schema
+      # @return [Hash{Integer=>Canon::ValidationError}]
+      def gate(obj1, obj2, schema)
+        schema = Canon::Validators::XsdValidator.compile(schema) if schema.is_a?(String)
+        failures = {}
+        [obj1, obj2].each_with_index do |obj, side|
+          Canon::Validators::XsdValidator.validate!(obj, schema: schema)
+        rescue Canon::ValidationError => e
+          failures[side] = e
+        end
+        failures
+      end
+    end
+  end
+end

data/lib/canon/comparison.rb

@@ -95,6 +95,7 @@ module Canon
     autoload :DiffNodeBuilder, "canon/comparison/diff_node_builder"
     autoload :Dimensions, "canon/comparison/dimensions"
     autoload :FormatDetector, "canon/comparison/format_detector"
+    autoload :SchemaGate, "canon/comparison/schema_gate"
     autoload :HtmlComparator, "canon/comparison/html_comparator"
     autoload :HtmlCompareProfile, "canon/comparison/html_compare_profile"
     autoload :HtmlParser, "canon/comparison/html_parser"
@@ -246,6 +247,33 @@ module Canon
                                                        :semantic_tree))
         end
 
+        # W5.1 schema gate: when a schema rides the options, both XML
+        # documents must pass the engine's XSD assessment BEFORE the
+        # diff runs — a validation failure is normative regardless of
+        # what the tree comparison would say.
+        if (xsd = opts[:xsd])
+          gate = SchemaGate.gate(obj1, obj2, xsd)
+          unless gate.empty?
+            diffs = gate.map do |side, error|
+              node = Diff::DiffNode.new(node1: side.zero? ? obj1 : obj2,
+                                        node2: side.zero? ? obj2 : obj1,
+                                        dimension: :schema_validation,
+                                        reason: error.message)
+              node.normative = true # a schema failure is normative by definition
+              node
+            end
+            return false unless opts[:verbose]
+
+            return ComparisonResult.new(
+              differences: diffs,
+              preprocessed_strings: [obj1.to_s, obj2.to_s],
+              format: opts[:format] || :xml,
+              algorithm: :dom,
+              original_strings: [obj1.to_s, obj2.to_s],
+            )
+          end
+        end
+
         if %i[semantic semantic_tree].include?(opts[:diff_algorithm])
           return semantic_diff(obj1, obj2, opts)
         end

data/lib/canon/digest.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+require "openssl"
+
+module Canon
+  # W5.3 — canonical digests: the hash of a document's canonical form
+  # as a first-class API for deduplication and change detection.
+  #
+  # The digest is taken over the format's CANONICAL form — the form
+  # under which the comparison pipeline deems documents equivalent:
+  # XML rides Canonical XML 1.1 (attribute order sorted,
+  # namespace-normalized); JSON/YAML ride the key-sorted forms; HTML
+  # rides the whitespace-law form with sorted attributes. Two
+  # documents that compare equivalent under the canonical form
+  # produce identical digests. The digests are stable across releases
+  # for as long as the canonical form is (the digest-stability suite
+  # pins the bytes per release pair).
+  module Digest
+    DEFAULT_ALGORITHM = "sha256"
+
+    class << self
+      # @param content [String] the document
+      # @param format [Symbol] the format (see SUPPORTED_FORMATS)
+      # @param algorithm [String, Symbol] any OpenSSL digest name
+      # @return [String] the hex digest of the canonical form
+      def digest(content, format, algorithm: DEFAULT_ALGORITHM)
+        OpenSSL::Digest.new(algorithm.to_s)
+          .hexdigest(canonical_form(content, format))
+      end
+
+      # The canonical form the digest rides: XML's is C14N (the
+      # pretty-printed form preserves attribute order and is NOT
+      # canonical); every other format's formatter output IS the
+      # canonical form.
+      def canonical_form(content, format)
+        if format.to_sym == :xml
+          Formatters::XmlFormatter.format(content, pretty: false)
+        else
+          Canon.format(content, format)
+        end
+      end
+    end
+  end
+end

data/lib/canon/validators/xsd_validator.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+require "leptris" # the XSD lane rides the engine's tier-1 validator
+# (libleptris >= 1.9.321, leptris#1075)
+
+module Canon
+  module Validators
+    # XSD validation (W5.1) through the engine's tier-1 validator:
+    # schema compilation, whole-instance assessment, enumerated
+    # failures. The schema is a compiled `Leptris::XML::XSD::Schema`
+    # — callers validating many documents against one schema compile
+    # once and reuse (compilation is the expensive step).
+    #
+    #     schema = Canon::Validators::XsdValidator.compile(schema_xml)
+    #     Canon::Validators::XsdValidator.validate!(xml, schema: schema)
+    class XsdValidator < BaseValidator
+      # Compile a schema from XSD text. Raises Canon::ValidationError
+      # when the text is not well-formed XML, and when the engine
+      # reports schema-level problems.
+      #
+      # @param schema_xml [String] the XSD document
+      # @return [Leptris::XML::XSD::Schema] the compiled schema
+      def self.compile(schema_xml)
+        schema = Leptris::XML::XSD.compile(schema_xml)
+        if (detail = schema.error)
+          raise Canon::ValidationError.new(
+            "schema invalid: #{detail}",
+            format: :xml,
+          )
+        end
+        schema
+      end
+
+      # Validate an XML instance against a compiled schema
+      #
+      # @param input [String] the XML instance
+      # @param schema [Leptris::XML::XSD::Schema] a compiled schema
+      # @raise [Canon::ValidationError] if the instance fails
+      #   assessment; the message carries the first failure, details
+      #   carry the full enumerated list
+      # @return [void]
+      def self.validate!(input, schema:)
+        return if input.nil? || input.strip.empty?
+
+        doc = Leptris::XML.parse(input, readonly: true)
+        errors = schema.validate_errors(doc)
+        return if errors.empty?
+
+        raise Canon::ValidationError.new(
+          errors.first.to_s,
+          format: :xml,
+          details: errors.join("\n"),
+        )
+      end
+    end
+  end
+end

data/lib/canon/validators.rb

@@ -7,6 +7,7 @@ module Canon
     autoload :HtmlValidator, "canon/validators/html_validator"
     autoload :JsonValidator, "canon/validators/json_validator"
     autoload :XmlValidator, "canon/validators/xml_validator"
+    autoload :XsdValidator, "canon/validators/xsd_validator"
     autoload :YamlValidator, "canon/validators/yaml_validator"
   end
 end

data/lib/canon/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Canon
-  VERSION = "0.3.115"
+  VERSION = "0.3.116"
 end

data/lib/canon.rb

@@ -32,6 +32,7 @@ module Canon
   autoload :Cli, "canon/cli"
   autoload :ColorDetector, "canon/color_detector"
   autoload :DiffFormatter, "canon/diff_formatter"
+  autoload :Digest, "canon/digest"
   autoload :Json, "canon/json"
 
   SUPPORTED_FORMATS = %i[xml yaml json html html4 html5 string].freeze
@@ -84,5 +85,15 @@ module Canon
     define_singleton_method("format_#{format}") do |content|
       format(content, format)
     end
+
+    define_singleton_method("digest_#{format}") do |content, algorithm: Canon::Digest::DEFAULT_ALGORITHM|
+      Canon::Digest.digest(content, format, algorithm: algorithm)
+    end
+  end
+
+  # The canonical digest of a document (W5.3): the hash of its
+  # canonical form. See Canon::Digest for the stability contract.
+  def self.digest(content, format = :xml, algorithm: Canon::Digest::DEFAULT_ALGORITHM)
+    Canon::Digest.digest(content, format, algorithm: algorithm)
   end
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: canon
 version: !ruby/object:Gem::Version
-  version: 0.3.115
+  version: 0.3.116
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-10-23 00:00:00.000000000 Z
+date: 2026-10-24 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: diff-lcs
@@ -267,6 +267,7 @@ files:
 - lib/canon/comparison/pipeline.rb
 - lib/canon/comparison/profile_definition.rb
 - lib/canon/comparison/ruby_object_comparator.rb
+- lib/canon/comparison/schema_gate.rb
 - lib/canon/comparison/strategies.rb
 - lib/canon/comparison/strategies/base_match_strategy.rb
 - lib/canon/comparison/strategies/match_strategy_factory.rb
@@ -338,6 +339,7 @@ files:
 - lib/canon/diff_formatter/legend.rb
 - lib/canon/diff_formatter/pretty_diff_formatter.rb
 - lib/canon/diff_formatter/theme.rb
+- lib/canon/digest.rb
 - lib/canon/errors.rb
 - lib/canon/formatters.rb
 - lib/canon/formatters/html4_formatter.rb
@@ -404,6 +406,7 @@ files:
 - lib/canon/validators/html_validator.rb
 - lib/canon/validators/json_validator.rb
 - lib/canon/validators/xml_validator.rb
+- lib/canon/validators/xsd_validator.rb
 - lib/canon/validators/yaml_validator.rb
 - lib/canon/version.rb
 - lib/canon/xml.rb