parsanol 1.3.45-arm64-darwin → 1.3.46-arm64-darwin

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6725276c28acbe061606fca57771e612c09fdfbf1586eefbfaba0b218c5dcd25
-  data.tar.gz: 831dadd77bda92f1e299931e7eeda78b5854ffd244a57e29e8e7215bc728ec02
+  metadata.gz: 4f030ddf86028adfeda97de5c841b53a474ea939f997b3db2df30e089093ea94
+  data.tar.gz: 33c565b4b973793102b1a14c7c30963a5f1063639640af60f91836a7e7dbd11f
 SHA512:
-  metadata.gz: a1e4e3286ecdacc416df1a7569b874e88c71e5763d020874aa80e653742372b75392a410d4b2567650282ddc194a042e55aa6cf6959452c16436b4f1868ef488
-  data.tar.gz: d49010e87af19a5c958d77d03c6ad08462db15bbf2e57cf0822dcc34a192aead6d06161985ae9946a523c7abf08664508484f77aef1c296564dde1d17c56d249
+  metadata.gz: 3873ee15d9f7cd59123623738548ee8990cbe2fbff3d96cf3f995c3de30c9b45cb6e125531ba1aa40da3c7ee3eda6d316bd43e83b1a2a5f545898a571d883214
+  data.tar.gz: 5fe62804addb85b981c7d69cb0679a71c0fbe74e408f4e5cc2c3f0ac46198946c1b90e92af57fb2a4fb0ad964cc71ccad4410a4cc99d9469fec1a0fee5dd1f72

data/lib/parsanol/tree_diff.rb

@@ -0,0 +1,116 @@
+# frozen_string_literal: true
+
+module Parsanol
+  # Explains the first difference between two parse trees.
+  #
+  # Built for engine-parity debugging (parsanol-ruby#83): when
+  # `tree_ruby != tree_native`, `TreeDiff.why` pinpoints the first
+  # divergent node instead of leaving you to eyeball two inspect
+  # dumps.
+  #
+  # @example
+  #   Parsanol::TreeDiff.why(ruby_tree, native_tree)
+  #   # => { path: "paragraph.lines",
+  #   #      why: "kind mismatch: Array vs Hash",
+  #   #      ruby: "Array(1)",
+  #   #      native: "Hash{text, line_break}" }
+  #
+  # Returns nil when the trees are equal.
+  module TreeDiff
+    module_function
+
+    def why(left, right, max_depth: 200)
+      step(left, right, [], 0, max_depth)
+    end
+
+    def step(left, right, path, depth, max_depth)
+      if depth > max_depth
+        return { path: format_path(path), why: "depth limit exceeded", ruby: kind(left),
+                 native: kind(right) }
+      end
+      containers = (left.is_a?(Hash) && right.is_a?(Hash)) ||
+        (left.is_a?(Array) && right.is_a?(Array))
+      # Containers always descend: Hash#== would short-circuit equal via
+      # Slice's content-only ==, hiding offset drift.
+      return nil if !containers && equal_values?(left, right)
+
+      if left.is_a?(Hash) && right.is_a?(Hash)
+        only_left = left.keys - right.keys
+        only_right = right.keys - left.keys
+        if only_left.any? || only_right.any?
+          return { path: format_path(path),
+                   why: "key mismatch: ruby-only #{only_left.inspect}, " \
+                        "native-only #{only_right.inspect}",
+                   ruby: kind(left), native: kind(right) }
+        end
+        left.each do |key, value|
+          if right.key?(key)
+            found = step(value, right[key], path + [key], depth + 1, max_depth)
+            return found if found
+          end
+        end
+        nil
+      elsif left.is_a?(Array) && right.is_a?(Array)
+        if left.length != right.length
+          return { path: format_path(path),
+                   why: "size mismatch: ruby #{left.length} vs native #{right.length}",
+                   ruby: "Array(#{left.length})", native: "Array(#{right.length})" }
+        end
+        left.each_with_index do |value, index|
+          found = step(value, right[index], path + ["[#{index}]"], depth + 1, max_depth)
+          return found if found
+        end
+        nil
+      elsif left.is_a?(::Parsanol::Slice) && right.is_a?(::Parsanol::Slice)
+        if left.content == right.content
+          { path: format_path(path),
+            why: "offset drift: #{left.offset} vs #{right.offset}",
+            ruby: kind(left), native: kind(right) }
+        else
+          { path: format_path(path),
+            why: "content mismatch: #{left.content.inspect} vs #{right.content.inspect}",
+            ruby: kind(left), native: kind(right) }
+        end
+      else
+        { path: format_path(path), why: "kind mismatch: #{kind(left)} vs #{kind(right)}",
+          ruby: kind(left), native: kind(right) }
+      end
+    end
+
+    # Equality for parity purposes: Slices must match on content AND
+    # offset (position drift is a real divergence), and a Slice never
+    # equals a plain String here even though Slice#== would allow it —
+    # engines that disagree on type disagree on the tree.
+    def equal_values?(left, right)
+      left_is_slice = left.is_a?(::Parsanol::Slice)
+      right_is_slice = right.is_a?(::Parsanol::Slice)
+      if left_is_slice || right_is_slice
+        left_is_slice && right_is_slice &&
+          left.content == right.content && left.offset == right.offset
+      else
+        left == right
+      end
+    end
+
+    def kind(item)
+      case item
+      when ::Parsanol::Slice then "Slice(#{item.content.inspect}@#{item.offset})"
+      when Hash then "Hash{#{item.keys.join(', ')}}"
+      when Array then "Array(#{item.length})"
+      when String then "String(#{item.inspect})"
+      when nil then "nil"
+      else item.class.name
+      end
+    end
+
+    def format_path(path)
+      path.each_with_index.inject(+"") do |acc, (part, i)|
+        if i.zero? || part.to_s.start_with?("[")
+          acc << part.to_s
+        else
+          acc << "." << part.to_s
+        end
+      end
+    end
+  end
+end

data/lib/parsanol/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Parsanol
-  VERSION = "1.3.45"
+  VERSION = "1.3.46"
 end

data/lib/parsanol.rb

@@ -266,6 +266,7 @@ module Parsanol
 
   autoload :Expression, "parsanol/expression"
   autoload :IncrementalSession, "parsanol/incremental"
+  autoload :TreeDiff, "parsanol/tree_diff"
 end
 
 require "parsanol/version"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: parsanol
 version: !ruby/object:Gem::Version
-  version: 1.3.45
+  version: 1.3.46
 platform: arm64-darwin
 authors:
 - Ribose Inc.
@@ -114,6 +114,7 @@ files:
 - lib/parsanol/streaming_parser.rb
 - lib/parsanol/string_view.rb
 - lib/parsanol/transform.rb
+- lib/parsanol/tree_diff.rb
 - lib/parsanol/version.rb
 - lib/parsanol/vm.rb
 - lib/parsanol/wasm/README.md