canon 0.3.22 → 0.3.24

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4a369d56aae65493ad94c6352f01a15915eb0af020cde2c98868b7d51a8b0658
-  data.tar.gz: f667f5bf42ed4f1e581ee32951d561653187c06b74b6b996f9bcd1bb9fb0f073
+  metadata.gz: e1d317692d756e058f2a4fb6865fffa4240744ac1b7cf8c83cb026552acb3f16
+  data.tar.gz: b993bde4273af1fdfe30d05b43bc0e642b9c3b80d857dc437196d2e7ea20567f
 SHA512:
-  metadata.gz: 6741dac3a19b779fbbd9fe49edaa7f3d6c71497fe4a1cc6339eb65f0d749bcfe9e0800323cb321f4cfd35a756e0ebfab5f8740f8c3aa5e895b70d7c71adc3a84
-  data.tar.gz: 8a360875b2c5597c9e87e81eb0a8037979efa6b8166fe18155a68efc432626d4efebc1aa8ad82ea66ec398681aa1d03f83d35aa1c8fe0684e74a616f0ee96913
+  metadata.gz: 6ee303aab423e1bfb48b754b441c8e70b307af2a03956bd1cb7c5998dcb575cfc57c9c6ba1d02a22af74717cfbd8aaa1f05b88a52cc698da6e8547e3a0a25ce8
+  data.tar.gz: a2de4ba755d59ecd72bfe50e53f6fea6c1136cbc98fda6886c22f5240098a84235d304040dcefb8e1d882a9bab27228f86030bf784b297cbb29df1c745a622af

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; `Canon::JsonParsing` mirrors it for JSON (the same yeptris engine serves both — `Yeptris::YAML.load` auto-detects JSON and routes to the native C-API materializer; JSON falls back to stdlib unless `YamlBackend.yeptris_native?`, since the FFI ladder is ~29x slower than the stdlib C extension). `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#30 sexagesimal scalars, #31 >64-bit integers — #29 empty documents was fixed in 0.1.12); `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/json_comparator.rb

@@ -64,7 +64,7 @@ module Canon
           return obj unless obj.is_a?(String)
 
           begin
-            JSON.parse(obj)
+            Canon::JsonParsing.parse(obj)
           rescue JSON::ParserError
             obj
           end

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

@@ -17,7 +17,7 @@ module Canon
         # Return as-is if already parsed
         return json if json.is_a?(Hash) || json.is_a?(Array)
 
-        JSON.parse(json)
+        Canon::JsonParsing.parse(json)
       end
 
       def self.sort_json_keys(obj)

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

@@ -0,0 +1,27 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Canon
+  # The only place canon talks to a JSON engine. The yeptris fast path
+  # (fused C-API materializer, on par with the stdlib C extension)
+  # engages through Yeptris::YAML.load's JSON auto-detection; without
+  # the native materializer the stdlib parser serves, unchanged.
+  # Errors normalize to JSON::ParserError so canon's rescues hold on
+  # both engines.
+  module JsonParsing
+    module_function
+
+    def parse(json)
+      if Canon::YamlBackend.yeptris_native?
+        begin
+          ::Yeptris::YAML.load(json)
+        rescue ::Yeptris::ParseError, ::FFI::NullPointerError => e
+          raise JSON::ParserError, e.message
+        end
+      else
+        JSON.parse(json)
+      end
+    end
+  end
+end

data/lib/canon/validators/json_validator.rb

@@ -20,7 +20,7 @@ module Canon
         return if input.is_a?(Hash) || input.is_a?(Array) # Already parsed
         return if input.strip.empty?
 
-        JSON.parse(input)
+        Canon::JsonParsing.parse(input)
       rescue JSON::ParserError => e
         # Extract position from error message
         position = extract_position(e.message)

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.24"
 end

data/lib/canon/yaml_backend.rb

@@ -0,0 +1,72 @@
+# 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
+
+      # The JSON fast path needs the fused C-API materializer
+      # (Yeptris::Native — load_json) specifically: the FFI ladder is
+      # ~29x slower than the stdlib JSON C extension, so JSON loads
+      # fall back to stdlib when only FFI is present.
+      def yeptris_native?
+        yeptris? && yeptris_available? && !defined?(::Yeptris::Native).nil?
+      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,9 @@ 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/json_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.24
 platform: ruby
 authors:
 - Ribose Inc.
@@ -332,6 +332,7 @@ files:
 - lib/canon/html.rb
 - lib/canon/html/data_model.rb
 - lib/canon/html/nokogiri_support.rb
+- lib/canon/json_parsing.rb
 - lib/canon/options.rb
 - lib/canon/options/cli_generator.rb
 - lib/canon/options/registry.rb
@@ -407,6 +408,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