canon 0.3.49 → 0.3.51

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8f3f2bed07760530a3f122f18e184ac0e925db9d6551bacc46ef896552fb79ce
-  data.tar.gz: 4de5e38b9be98f354a843bb3fdd1c725534fab28f6078cbf95a7c278d0c2596b
+  metadata.gz: f61c2faf1fb2cddf94fac6e26f2e488525fb35bab80c11a0c044a7e31ebf590c
+  data.tar.gz: c3f30512ba09c3110fe517306ec1588eead657014c90e4cb229dba7d0b5d43ed
 SHA512:
-  metadata.gz: '002904526d2626e462005b4a3627540a1d6587c458b60adb871ad03134054485c2712707579106f727fa00066b213d8db903f96be5d695470aed08ec82157461'
-  data.tar.gz: 537566ace8ff29b3124bbd9fd2789250d95d539de60b0e8ba89a3d5ebf83dee871fe0e7525d8d76381286f8adf71886957a3c4a29b1887f861fc0201b44bd862
+  metadata.gz: abb829d4a9944c9b191cd2da72a5677e775e74d5048e106f9170e2de3a9e0d0165d458d14f06227cfb1a991c99d37c2ab51957b260bad0de9eafb248b036b056
+  data.tar.gz: 0a8d8d11482a3aec546a040f21eebfd2888d04d44d9397039b9448b8167f0fac89e5eb656fa6b5c3210db6bae0b0c2ffa1d0b27007023ce9afea70e18dbdf138

data/CLAUDE.md

@@ -149,7 +149,7 @@ Engine A/B testing: `CANON_XML_BACKEND=nokogiri bundle exec rspec` (or `=moxml`
 
 ### YAML Engines
 
-`Canon::YamlBackend` selects the YAML engine: `:yeptris` (default — Marshal bulk materialization in yeptris 0.1.28, 4.5–5x Psych load) or `:psych` (`CANON_YAML_BACKEND=psych` forces the stdlib engine). The default follows availability: yeptris when loadable, Psych otherwise. `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. **JSON defaults to the strict yeptris surface whenever the native materializer is installed** (yeptris 0.1.13.4 ships platform gems — zero compilation, zero env; parity spec-pinned to `JSON.parse` upstream). The parity gate (`spec/canon/yaml_engine_parity_spec.rb`) ran clean after yeptris-ruby #29/#30/#31/#37 all closed (0.1.15.1), so YAML loads flip to yeptris by default; the spec stays as the executable gate for future yeptris releases. Never `require "yeptris/psych"` — it rebinds the global `::Psych` constant for the whole process; only the namespaced `Yeptris::YAML` API is used.
+`Canon::YamlBackend` selects the YAML engine: `:yeptris` (default — Marshal bulk materialization in yeptris 0.1.28, 4.5–5x Psych load) or `:psych` (`CANON_YAML_BACKEND=psych` forces the stdlib engine). The default follows availability: yeptris when loadable, Psych otherwise. `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 dumps also default to yeptris (0.6.5+'s emitter is byte-identical to Psych across the dump corpus — nil/Time/special-float/block-scalar/key-type families, yeptris#290/#300 closed; `header: true` supplies the `---` marker; `YamlParsing.dump` is the seam). **JSON defaults to the strict yeptris surface whenever the native materializer is installed** (yeptris 0.1.13.4 ships platform gems — zero compilation, zero env; parity spec-pinned to `JSON.parse` upstream). The parity gate (`spec/canon/yaml_engine_parity_spec.rb`) includes dump-lane byte-parity pins (yeptris#290/#300 closed in 0.6.5) — the executable gate for future yeptris releases. Never `require "yeptris/psych"` — it rebinds the global `::Psych` constant for the whole process; only the namespaced `Yeptris::YAML` API is used.
 
 ### Format Detection
 

data/lib/canon/comparison/yaml_comparator.rb

@@ -70,8 +70,8 @@ module Canon
 
           if opts[:verbose]
             # Format YAML for display
-            yaml_str1 = obj1.is_a?(String) ? obj1 : YAML.dump(obj1)
-            yaml_str2 = obj2.is_a?(String) ? obj2 : YAML.dump(obj2)
+            yaml_str1 = obj1.is_a?(String) ? obj1 : Canon::YamlParsing.dump(obj1)
+            yaml_str2 = obj2.is_a?(String) ? obj2 : Canon::YamlParsing.dump(obj2)
 
             ComparisonResult.new(
               differences: differences,

data/lib/canon/comparison.rb

@@ -597,8 +597,7 @@ module Canon
           require "json"
           JSON.pretty_generate(doc)
         when :yaml
-          require "yaml"
-          doc.to_yaml
+          Canon::YamlParsing.dump(doc)
         else
           doc.to_s
         end

data/lib/canon/diff_formatter/by_line/xml_formatter.rb

@@ -118,6 +118,13 @@ module Canon
           after = diff_node.serialized_after&.split("\n") || []
           fmt = diff_node.formatting?
           lines = []
+          header = parent_chain(diff_node.path)
+          if header
+            lines << Canon::Diff::DiffLine.new(
+              line_number: nil, new_position: nil,
+              content: header, type: :location_header
+            )
+          end
           require "diff/lcs" unless defined?(::Diff::LCS)
 
           ::Diff::LCS.sdiff(before, after).each do |change|
@@ -156,6 +163,27 @@ module Canon
           lines
         end
 
+        # Display chain of a DiffNode's ancestor elements, e.g.
+        # "bibitem > formattedref" — gives the blank-numbered
+        # unlocated lines a readable home (#86).
+        def parent_chain(path)
+          return nil if path.nil?
+
+          segments = path.split("/").reject(&:empty?)
+          return nil if segments.length < 2
+
+          chain = segments[0...-1].filter_map do |seg|
+            seg[/\A(?:\{[^}]+\})?([a-zA-Z0-9_:-]+)/, 1]
+          end
+          # Comparator paths repeat the element name before the node
+          # segment ("formattedref/formattedref/text()") — collapse
+          # consecutive repeats for display.
+          collapsed = chain.each_with_object([]) do |name, acc|
+            acc << name unless acc.last == name
+          end
+          collapsed.join(" > ")
+        end
+
         # The nearest preceding node (in @differences walk order)
         # that the enricher DID locate.
         def preceding_located(diff_node)
@@ -225,6 +253,9 @@ module Canon
               new_num = (diff_line.new_position || diff_line.line_number)&.+(1)
               output << format_unified_line(old_num, new_num, " ",
                                             diff_line.content)
+            when :location_header
+              output << format_location_header(diff_line.content)
+
             when :removed
               line_num = diff_line.line_number&.+(1)
               formatting = diff_line.formatting?
@@ -992,6 +1023,18 @@ module Canon
           end
         end
 
+        # Dimmed section header for unlocated-node contexts (#86):
+        # "⋯ in bibitem > formattedref"
+        def format_location_header(chain)
+          blank = " " * @line_num_width
+          text = "    ⋯ in #{chain}"
+          if @use_color
+            "#{blank}|#{blank}  | #{colorize(text, :light_black)}"
+          else
+            "#{blank}|#{blank}  | #{text}"
+          end
+        end
+
         def format_unified_line(old_num, new_num, marker, content, color = nil,
 informative: false, formatting: false)
           old_str = old_num ? "%#{@line_num_width}d" % old_num : " " * @line_num_width

data/lib/canon/formatters/yaml_formatter.rb

@@ -8,7 +8,7 @@ module Canon
     class YamlFormatter
       def self.format(yaml)
         parsed = parse(yaml)
-        sort_yaml_keys(parsed).to_yaml
+        Canon::YamlParsing.dump(sort_yaml_keys(parsed))
       end
 
       def self.parse(yaml)

data/lib/canon/version.rb

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

data/lib/canon/yaml_parsing.rb

@@ -18,6 +18,21 @@ module Canon
     # call site) — a canonicalizer treats anchors as content: yeptris
     # resolves them unconditionally, so :true keeps both engines
     # behavior-identical.
+    # Serialize a Ruby object graph to YAML. yeptris 0.6.5+'s
+    # emitter is byte-identical to Psych across canon's dump corpus
+    # (nil/Time/special-float/block-scalar/key-type families —
+    # yeptris#290/#300 closed) with header: true supplying the
+    # "---" document start Psych emits; Psych serves when yeptris
+    # is inactive (CANON_YAML_BACKEND=psych forces it for dumps as
+    # for loads).
+    def dump(obj)
+      if YamlBackend.yeptris?
+        ::Yeptris::YAML.dump(obj, header: true)
+      else
+        YAML.dump(obj)
+      end
+    end
+
     def safe_load(yaml, permitted_classes: [Symbol, Date, Time],
                   aliases: true)
       if YamlBackend.yeptris?

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: canon
 version: !ruby/object:Gem::Version
-  version: 0.3.49
+  version: 0.3.51
 platform: ruby
 authors:
 - Ribose Inc.
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2026-09-16 00:00:00.000000000 Z
+date: 2026-09-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: diff-lcs