canon 0.3.22 → 0.3.23

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a369d56aae65493ad94c6352f01a15915eb0af020cde2c98868b7d51a8b0658
-  data.tar.gz: f667f5bf42ed4f1e581ee32951d561653187c06b74b6b996f9bcd1bb9fb0f073
+  metadata.gz: 7e3fda4e37d9ca6cf584389c0ffec06c70811ec488910377151ed8ee29f20a35
+  data.tar.gz: cb73f6f95b16ce10b9ada9f13d1e91eaad0a4bce416d84ddfb49439227f270d5
 SHA512:
-  metadata.gz: 6741dac3a19b779fbbd9fe49edaa7f3d6c71497fe4a1cc6339eb65f0d749bcfe9e0800323cb321f4cfd35a756e0ebfab5f8740f8c3aa5e895b70d7c71adc3a84
-  data.tar.gz: 8a360875b2c5597c9e87e81eb0a8037979efa6b8166fe18155a68efc432626d4efebc1aa8ad82ea66ec398681aa1d03f83d35aa1c8fe0684e74a616f0ee96913
+  metadata.gz: 48a6dacc76c75c234a34583264f0cd3816c643bda7152ccbeee62cb4057fd370c70b168414bca515addc400de5ea12dacb82b9a356d35e4421596bff0109806b
+  data.tar.gz: a33a5b36fbd98f43d4832dbb275737726f5e9dc1786b91fc34313684a8e431724e3f169a426c18af3d90a15be1fb9a4970e561ef25d2f576ff52229cfebc1829

data/CLAUDE.md

@@ -143,6 +143,10 @@ Engine parity is complete through libleptris 1.9.8 / leptris-ruby 1.9.33 / moxml
 
 Engine A/B testing: `CANON_XML_BACKEND=nokogiri bundle exec rspec` (or `=moxml` to force leptris when it isn't the resolved default). The default suite must stay green under BOTH values; the only expected pendings are the upstream-tracked ones. The benchmark header (`rake performance:quick`) reports the active engine.
 
+### YAML Engines
+
+`Canon::YamlBackend` selects the YAML engine: `:psych` (default) or `:yeptris` (FFI over libyeptris, the YAML counterpart of the leptris XML stack — `CANON_YAML_BACKEND=yeptris` opts in; the optional `yeptris` Gemfile group must be enabled). `Canon::YamlParsing` is the single gateway for string loads; `YAML.dump` stays on Psych everywhere — canonical output bytes are canon's product and the writers differ. The default stays `:psych` until the yeptris Psych-parity gaps close (yeptris-ruby#29 empty documents, #30 sexagesimal scalars, #31 >64-bit integers); `spec/canon/yaml_engine_parity_spec.rb` is the executable gate, with upstream-tracked cases pending. Never `require "yeptris/psych"` — it rebinds the global `::Psych` constant for the whole process; only the namespaced `Yeptris::YAML` API is used.
+
 ### Format Detection
 
 `Canon::Comparison::FormatDetector` auto-detects format from string content or object type (Moxml::Node → XML, Nokogiri::HTML → HTML, Hash → JSON, etc.). HTML4 vs HTML5 is determined by DOCTYPE.

data/lib/canon/comparison/yaml_comparator.rb

@@ -90,7 +90,7 @@ module Canon
         def parse_yaml(obj)
           return obj unless obj.is_a?(String)
 
-          YAML.safe_load(obj, aliases: true)
+          Canon::YamlParsing.safe_load(obj, aliases: true)
         end
       end
     end

data/lib/canon/formatters/yaml_formatter.rb

@@ -17,7 +17,7 @@ module Canon
         # Return as-is if already parsed
         return yaml if yaml.is_a?(Hash) || yaml.is_a?(Array)
 
-        YAML.safe_load(yaml, permitted_classes: [Symbol, Date, Time])
+        Canon::YamlParsing.safe_load(yaml)
       end
 
       def self.sort_yaml_keys(obj)

data/lib/canon/validators/yaml_validator.rb

@@ -22,7 +22,7 @@ module Canon
         return if input.is_a?(Hash) || input.is_a?(Array) # Already parsed
         return if input.strip.empty?
 
-        YAML.safe_load(input, permitted_classes: [Symbol, Date, Time])
+        Canon::YamlParsing.safe_load(input)
       rescue Psych::SyntaxError => e
         location = extract_location(e)
 

data/lib/canon/version.rb

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

data/lib/canon/yaml_backend.rb

@@ -0,0 +1,64 @@
+# frozen_string_literal: true
+
+module Canon
+  # Selection of the YAML engine: :psych (stdlib) or :yeptris
+  # (FFI over libyeptris — the YAML counterpart of the leptris XML
+  # stack).
+  #
+  # Mirrors XmlBackend's discipline (MECE — this module owns selection,
+  # YamlParsing owns the calls). The default stays :psych until the
+  # yeptris Psych-safe_load parity gaps close (yeptris-ruby#29 empty
+  # documents crash, #30 sexagesimal scalars, #31 >64-bit integers);
+  # yeptris is 3.1x faster at loading (measured, 2,000-item document),
+  # so CANON_YAML_BACKEND=yeptris opts in early and the default flips
+  # once the parity spec runs clean.
+  #
+  # Only the namespaced API (Yeptris::YAML) is ever used — requiring
+  # "yeptris/psych" rebinds the global ::Psych constant for the whole
+  # process, which a library must never do.
+  module YamlBackend
+    VALID_BACKENDS = %i[psych yeptris].freeze
+
+    class << self
+      def active
+        @active ||= begin
+          wanted = forced || :psych
+          # A forced yeptris without a loadable gem/native lib must
+          # degrade to Psych, not NameError in the gateway.
+          wanted = :psych if wanted == :yeptris && !yeptris_available?
+          wanted
+        end
+      end
+
+      def psych?
+        active == :psych
+      end
+
+      def yeptris?
+        active == :yeptris
+      end
+
+      def reset!
+        @active = nil
+      end
+
+      def yeptris_available?
+        return false if RUBY_ENGINE == "opal"
+
+        require "yeptris"
+        Yeptris::YAML.respond_to?(:load)
+      rescue LoadError, StandardError
+        false
+      end
+
+      private
+
+      def forced
+        value = ENV["CANON_YAML_BACKEND"].to_s.downcase
+        return nil unless VALID_BACKENDS.include?(value.to_sym)
+
+        value.to_sym
+      end
+    end
+  end
+end

data/lib/canon/yaml_parsing.rb

@@ -0,0 +1,36 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+module Canon
+  # The only place canon talks to a YAML engine. All string loads go
+  # through safe_load here (see XmlParsing for the XML equivalent);
+  # YAML.dump stays on Psych everywhere — canonical output bytes are
+  # canon's product and the writers differ.
+  module YamlParsing
+    module_function
+
+    # Psych::safe_load semantics. yeptris is safe-by-default plain
+    # data with Symbol/Date/Time built in (aliases resolve), so the
+    # permitted-class list is inherently satisfied; parse failures are
+    # normalized to Psych::SyntaxError so canon's rescues hold on both
+    # engines.
+    def safe_load(yaml, permitted_classes: [Symbol, Date, Time],
+                  aliases: false)
+      if YamlBackend.yeptris?
+        begin
+          ::Yeptris::YAML.load(yaml)
+        rescue ::Yeptris::ParseError => e
+          raise Psych::SyntaxError.new(nil, 0, 0, 0, e.message, "")
+        rescue ::FFI::NullPointerError
+          # yeptris-ruby#29: empty/comment-only input. Psych returns
+          # nil; mirror that until the upstream fix lands.
+          nil
+        end
+      else
+        YAML.safe_load(yaml, permitted_classes: permitted_classes,
+                             aliases: aliases)
+      end
+    end
+  end
+end

data/lib/canon.rb

@@ -5,6 +5,8 @@ require "canon/errors"
 require "nokogiri" unless RUBY_ENGINE == "opal"
 require "canon/xml_backend"
 require "canon/xml_parsing"
+require "canon/yaml_backend"
+require "canon/yaml_parsing"
 require "canon/config"
 require "canon/data_model"
 require "canon/xml"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: canon
 version: !ruby/object:Gem::Version
-  version: 0.3.22
+  version: 0.3.23
 platform: ruby
 authors:
 - Ribose Inc.
@@ -407,6 +407,8 @@ files:
 - lib/canon/xml/xpath_engine.rb
 - lib/canon/xml_backend.rb
 - lib/canon/xml_parsing.rb
+- lib/canon/yaml_backend.rb
+- lib/canon/yaml_parsing.rb
 - lib/tasks/benchmark_runner.rb
 - lib/tasks/performance.rake
 - lib/tasks/performance_comparator.rb