specdiff 0.2.0 → 0.3.0.rc2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8d698240eae3e0f8f38c22b66df23efb1076b14879a7093c3d3e33aebddd37c9
-  data.tar.gz: 29e6198145c5a9ede875a26066a33e599561fe82277c6eb8bdb475c291304c9b
+  metadata.gz: 8a33e470568352bc5fb3079f5aa3cf9933f5c02d7e28aae98847b9165a0d6a86
+  data.tar.gz: ad35a03f7da4fee967890515447eb0d2a2a4ec927d78d2458198177166aa43c6
 SHA512:
-  metadata.gz: cb5b52f47732689bc8322b840436d4c27fb048dbe20e9e0d8501b3120137500b7a9230a9818c31e049aa22715c251166d807b4e01111695406470c6b314c13c5
-  data.tar.gz: 103362c058c1e260dc9a9c3f1bd06b06d39ab25c1818e001c7160eb61ceb741d549b4f9c6fb974bb27614456ab2d34dfae6732bc6d842d42346bd62abe1fc331
+  metadata.gz: 6fa7b514db6ccb4a7216f317184e6de0dae0fb8ad762222c4d09ee589300ae4d71a38549710ceb8191e5276958fcdfc27e65dcb50f0353e64065492c58a28b8a
+  data.tar.gz: bf66592a0f9d787058dcdd3b27910863abdc70cdeb177ddfb84d6ddfa9973adee345fa8c90f821f6a8dbab94898db375414eeef8e9a306b532b9aa472f615280

data/.gitignore

@@ -0,0 +1,14 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status
+
+# local installed gem bundles, ala node_modules for npm
+.gem-bundle/

data/CHANGELOG.md

@@ -7,6 +7,35 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.3.0.rc2] - 2024-04-05
+
+### Changed
+
+- Rework how hashdiff's output gets printed.
+- Rework switching heuristic between text diff/hashdiff in hash differ.
+
+### Fixed
+
+- The RSpec integration now inspects hashes and arrays recursively. (Like rspec does by default)
+- RSpec integration no longer breaks description output of matchers when using multi matchers (like .all or .and)
+- The hash differ now deals with recursive hashes and arrays
+- RSpec integration no longer breaks description output of matchers that are part of a diff inside an array or hash. (like when doing `match([have_attributes(...)])`)
+
+## [0.3.0-rc1] - 2024-04-02
+
+### Added
+
+- Add rspec integration. `require "specdiff/rspec"` The rspec integration will cause rspec's differ to be replaced entirely with specdiff. It will also cause rspec's inspect (object formatter) to be replaced with Specdiff's inspect.
+- Add `Specdiff.diff_inspect` method, which is a wrapper for `#inspect` with some extra logic to make diffs look better.
+- Add `Specdiff.hashprint` method, which prints hashes/arrays recursively in a way that is friendly to a text differ.
+
+### Changed
+
+- Improve contrast for some elements of the text differ
+- Improve hash diffing. Introduce heuristic that decides whether a text diff of the hashes or the hashdiff gem's output is better for the situation.
+- No longer produces a text diff of booleans
+- No longer produces a text diff if both strings are a single line. (This would be useless since the diff is line-based.)
+
 ## [0.2.0] - 2023-12-04
 
 ### Changed

data/README.md

@@ -11,7 +11,24 @@ dropping the content type requirement.
 Specdiff automagically detects the types of provided data and prints a suitable
 diff between them.
 
-Check out the examples directory to see what it might look like.
+## Cool, what does it look like?
+
+When specdiff is enabled, webmock will produce a generic text diff using
+[`Diff::LCS`](https://github.com/halostatue/diff-lcs) (basically the same
+diff as rspec uses):
+
+![webmock_text_with_specdiff](./assets/webmock_text_with_specdiff.png)
+
+It will also produce a json [hashdiff](https://github.com/liufengyun/hashdiff),
+even if the request did not have the content type header:
+
+![d](./assets/webmock_json_with_specdiff.png)
+
+(The output of the json diff is experimental, feedback would be great!)
+
+You might also check out the `examples/` directory to play with it:
+
+`$ cd examples/webmock && bundle install`
 
 ## Installation
 
@@ -116,17 +133,16 @@ High level description of the heuristic specdiff implements
 
   - [ ] unit tests are passing (`$ bundle exec rake test`)
   - [ ] linter is happy (`$ bundle exec rake lint`)
-  - [ ] `$ cd examples/webmock && bundle install && bundle exec ruby json.rb` looks good
-  - [ ] `$ bundle exec ruby text.rb` looks good
+  - [ ] `examples/` look good
+  - [ ] check the package size using `$ bundle exec inspect_build`, make sure you haven't added any large files by accident
   - [ ] update the version number in `version.rb`
-  - [ ] make sure the `examples/` `Gemfile.lock` files are updated
+  - [ ] make sure the `examples/` `Gemfile.lock` files are updated (run bundle install)
+  - [ ] make sure `Gemfile.lock` is updated (run bundle install)
   - [ ] move unreleased changes to the next version in the [changelog](./CHANGELOG.md)
   - [ ] commit in the form "vX.X.X" and push
   - [ ] make sure the pipeline is green
   - [ ] `$ bundle exec rake release`
 
-To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
-
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub at https://github.com/odinhb/specdiff.

data/lib/specdiff/colorize.rb

@@ -25,7 +25,12 @@ module Specdiff::Colorize
     "\e[33m#{text}\e[0m"
   end
 
+  # this color may have bad contrast
   def blue(text)
     "\e[34m#{text}\e[0m"
   end
+
+  def cyan(text)
+    "\e[36m#{text}\e[0m"
+  end
 end

data/lib/specdiff/compare.rb

@@ -80,9 +80,9 @@ private
     elsif a.type == :text && b.type == :text
       Specdiff::Differ::Text
     elsif a.type == :hash && b.type == :hash
-      Specdiff::Differ::Hashdiff
+      Specdiff::Differ::Hash
     elsif a.type == :array && b.type == :array
-      Specdiff::Differ::Hashdiff
+      Specdiff::Differ::Hash
     else
       Specdiff::Differ::NotFound
     end

data/lib/specdiff/diff.rb

@@ -19,10 +19,15 @@
   end
 
   def inspect
-    if empty?
-      "<Specdiff::Diff (empty)>"
-    else
-      "<Specdiff::Diff w/ #{raw&.bytesize || 0} bytes of #raw diff>"
-    end
+    raw_diff = if empty?
+                 "empty"
+               elsif differ == ::Specdiff::Differ::Text
+                 bytes = raw&.bytesize || 0
+                 "#{bytes} bytes of #raw diff"
+               else
+                 "#{raw.inspect}"
+               end
+
+    "<Specdiff::Diff (#{a.type}/#{b.type}) (#{differ}) (#{raw_diff})>"
   end
 end

data/lib/specdiff/differ/hash.rb

@@ -0,0 +1,179 @@
+require "hashdiff"
+
+class Specdiff::Differ::Hash
+  extend ::Specdiff::Colorize
+
+  # The percentage of changes that must (potentially) be a key rename in a hash
+  # for text diffing to kick in. Expressed as a fraction of 1.
+  KEY_CHANGE_PERCENTAGE_THRESHOLD = 0.8
+
+  # The number of changes that must be detected by hashdiff before we print some
+  # extra newlines to better group extra/missing/new_values visually.
+  TOTAL_CHANGES_FOR_GROUPING_THRESHOLD = 9
+
+  def self.diff(a, b)
+    # array_path: true returns the path as an array, which differentiates
+    # between symbol keys and string keys in hashes, while the string
+    # representation does not.
+    # hmm it really seems like use_lcs: true gives much less human-readable
+    # (human-comprehensible) output when arrays are involved.
+    hashdiff_diff = ::Hashdiff.diff(
+      a.value, b.value,
+      array_path: true,
+      use_lcs: false,
+    )
+
+    return hashdiff_diff if hashdiff_diff.empty?
+
+    change_percentage = _calculate_change_percentage(hashdiff_diff)
+
+    if change_percentage <= KEY_CHANGE_PERCENTAGE_THRESHOLD
+      hashdiff_diff
+    else
+      a_text = ::Specdiff.hashprint(a.value)
+      b_text = ::Specdiff.hashprint(b.value)
+
+      text_diff = ::Specdiff.diff(a_text, b_text)
+
+      if text_diff.empty?
+        []
+      else
+        text_diff
+      end
+    end
+  end
+
+  def self._calculate_change_percentage(hashdiff_diff)
+    extra_keys = hashdiff_diff.count { |element| element[0] == "+" }
+    missing_keys = hashdiff_diff.count { |element| element[0] == "-" }
+    new_values = hashdiff_diff.count { |element| element[0] == "~" }
+    # puts "hashdiff_diff: #{hashdiff_diff.inspect}"
+    # puts "extra_keys: #{extra_keys.inspect}"
+    # puts "missing_keys: #{missing_keys.inspect}"
+    # puts "new_values: #{new_values.inspect}"
+
+    potential_changed_keys = [extra_keys, missing_keys].min
+    adjusted_extra_keys = extra_keys - potential_changed_keys
+    adjusted_missing_keys = missing_keys - potential_changed_keys
+    # puts "potential_changed_keys: #{potential_changed_keys.inspect}"
+    # puts "adjusted_extra_keys: #{adjusted_extra_keys.inspect}"
+    # puts "adjusted_missing_keys: #{adjusted_missing_keys.inspect}"
+
+    non_changed_keys = adjusted_extra_keys + adjusted_missing_keys + new_values
+    total_changes = non_changed_keys + potential_changed_keys
+    # puts "non_changed_keys: #{non_changed_keys.inspect}"
+    # puts "total_changes: #{total_changes.inspect}"
+
+    key_change_fraction = Rational(potential_changed_keys, total_changes)
+    key_change_percentage = key_change_fraction.to_f
+    # puts "key_change_fraction: #{key_change_fraction.inspect}"
+    # puts "key_change_percentage: #{key_change_percentage.inspect}"
+
+    key_change_percentage
+  end
+
+  def self.empty?(diff)
+    diff.raw.empty?
+  end
+
+  NEWLINE = "\n"
+
+  def self.stringify(diff)
+    result = +""
+    return result if diff.empty?
+
+    total_changes = diff.raw.size
+    group_with_newlines = total_changes >= TOTAL_CHANGES_FOR_GROUPING_THRESHOLD
+
+    # hashdiff returns a structure like so:
+    # change[0] = '+', '-' or '~'. denoting type (addition, deletion or change)
+    # change[1] = the path to the change, in array form
+    # change[2] = the value, or the from value in case of '~'
+    # change[3] = the to value, only present when '~'
+    changes_grouped_by_type = diff.raw.group_by { |change| change[0] }
+    if (changes_grouped_by_type.keys - ["+", "-", "~"]).size > 0
+      $stderr.puts(
+        "Specdiff: hashdiff returned unexpected types: #{diff.raw.inspect}"
+      )
+    end
+
+    deletions = changes_grouped_by_type["-"] || []
+    additions = changes_grouped_by_type["+"] || []
+    value_changes = changes_grouped_by_type["~"] || []
+
+    result << "@@ +#{additions.size}/-#{deletions.size}/~#{value_changes.size} @@"
+    result << NEWLINE
+
+    deletions.each do |change|
+      value = change[2]
+      path = _stringify_path(change[1])
+
+      result << "missing key: #{path} (#{::Specdiff.diff_inspect(value)})"
+      result << NEWLINE
+    end
+
+    if deletions.any? && additions.any? && group_with_newlines
+      result << NEWLINE
+    end
+
+    additions.each do |change|
+      value = change[2]
+      path = _stringify_path(change[1])
+
+      result << "  extra key: #{path} (#{::Specdiff.diff_inspect(value)})"
+      result << NEWLINE
+    end
+
+    if additions.any? && value_changes.any? && group_with_newlines
+      result << NEWLINE
+    end
+
+    value_changes.each do |change|
+      from = change[2]
+      to = change[3]
+      path = _stringify_path(change[1])
+
+      from_inspected = ::Specdiff.diff_inspect(from)
+      to_inspected = ::Specdiff.diff_inspect(to)
+      result << "  new value: #{path} (#{from_inspected} -> #{to_inspected})"
+      result << NEWLINE
+    end
+
+    colorize_by_line(result) do |line|
+      if line.start_with?("missing key:")
+        red(line)
+      elsif line.start_with?("  extra key:")
+        green(line)
+      elsif line.start_with?("  new value:")
+        yellow(line)
+      elsif line.start_with?("@@")
+        cyan(line)
+      else
+        reset_color(line)
+      end
+    end
+  end
+
+  PATH_SEPARATOR = ".".freeze
+
+  def self._stringify_path(path)
+    result = +""
+
+    path.each do |component|
+      if component.is_a?(Numeric)
+        result.chomp!(PATH_SEPARATOR)
+        result << "[#{component}]"
+      elsif component.is_a?(Symbol)
+        # by not inspecting symbols they look prettier than strings, but you
+        # can still tell the difference in the printed output
+        result << component.to_s
+      else
+        result << component.inspect
+      end
+
+      result << PATH_SEPARATOR
+    end
+
+    result.chomp(PATH_SEPARATOR)
+  end
+end

data/lib/specdiff/differ/not_found.rb

@@ -2,7 +2,7 @@
 class Specdiff::Differ::NotFound
   def self.diff(a, b)
     comparison = "!="
-    comparison = "=" if a.value == b.value
+    comparison = "==" if a.value == b.value
 
     a_representation = _representation_for(a)
     b_representation = _representation_for(b)

data/lib/specdiff/differ/text.rb

@@ -15,20 +15,32 @@ class Specdiff::Differ::Text
     b_value = b.value
 
     if a_value.encoding != b_value.encoding
-      return <<~MSG
+      return colorize_by_line(<<~MSG) do |line|
         Strings have different encodings:
           #{a.value.encoding.inspect} != #{b.value.encoding.inspect}
       MSG
+        # makes it stand out a bit more from the red of rspec output
+        reset_color(line)
+      end
     end
 
     diff = ""
 
+    # if there are no newlines then the text differ doesn't produce any valuable
+    # output. "word diffing" would improve this case.
+    if a_value.count(NEWLINE) <= 1 && b_value.count(NEWLINE) <= 1
+      return diff
+    end
+
     a_lines = a_value.split(NEWLINE).map! { _1.chomp }
     b_lines = b_value.split(NEWLINE).map! { _1.chomp }
+
+    file_length_difference = 0
+
     hunks = ::Diff::LCS.diff(a_lines, b_lines).map do |piece|
       ::Diff::LCS::Hunk.new(
-        a_lines, b_lines, piece, CONTEXT_LINES, 0,
-      )
+        a_lines, b_lines, piece, CONTEXT_LINES, file_length_difference,
+      ).tap { |hunk| file_length_difference = hunk.file_length_difference }
     end
 
     hunks.each_cons(2) do |prev_hunk, current_hunk|
@@ -36,7 +48,7 @@ class Specdiff::Differ::Text
         if current_hunk.overlaps?(prev_hunk)
           current_hunk.merge(prev_hunk)
         else
-          diff << prev_hunk.diff(:unified).to_s
+          diff << prev_hunk.diff(:unified)
         end
       ensure
         diff << NEWLINE
@@ -44,12 +56,14 @@ class Specdiff::Differ::Text
     end
 
     if hunks.last
-      diff << hunks.last.diff(:unified).to_s
+      diff << NEWLINE
+      diff << hunks.last.diff(:unified)
     end
 
     return diff if diff == ""
 
-    diff << "\n"
+    diff << NEWLINE
+    diff.lstrip!
 
     return colorize_by_line(diff) do |line|
       case line[0].chr
@@ -59,7 +73,7 @@ class Specdiff::Differ::Text
         red(line)
       when "@"
         if line[1].chr == "@"
-          blue(line)
+          cyan(line)
         else
           reset_color(line)
         end

data/lib/specdiff/differ.rb

@@ -4,4 +4,4 @@ end
 # require only the builtin differs, plugins are optionally loaded later
 require_relative "differ/not_found"
 require_relative "differ/text"
-require_relative "differ/hashdiff"
+require_relative "differ/hash"

data/lib/specdiff/hashprint.rb

@@ -0,0 +1,174 @@
+# Tries to print nested hash/array structures such that they are as convenient
+# as possible for a diffing algorithm designed for text (like source code).
+# Basically tries to reproduce consistent literal source code form for ruby
+# hashes and arrays and objects (although it falls back to #inspect).
+class Specdiff::Hashprint
+  def self.call(...)
+    new.call(...)
+  end
+
+  INDENTATION_SPACES = 2
+  SPACE = " ".freeze
+  COMMA = ",".freeze
+  NEWLINE = "\n".freeze
+
+  def call(thing)
+    @recursion_trail = []
+    @indentation_level = 0
+    @indentation_per_level = SPACE * INDENTATION_SPACES
+    @indent = ""
+    @skip_next_opening_indent = false
+
+    @output = StringIO.new
+
+    output(thing)
+
+    @output.string
+  end
+
+private
+
+  def recalculate_indent
+    @indent = @indentation_per_level * @indentation_level
+  end
+
+  def increase_indentation
+    @indentation_level += 1
+    recalculate_indent
+  end
+
+  def decrease_indentation
+    @indentation_level -= 1
+    recalculate_indent
+  end
+
+  def skip_next_opening_indent
+    @skip_next_opening_indent = true
+
+    nil
+  end
+
+  def this_indent_should_be_skipped
+    if @skip_next_opening_indent
+      @skip_next_opening_indent = false
+      true
+    else
+      false
+    end
+  end
+
+  def track_recursion(thing)
+    @recursion_trail.push(thing)
+    result = yield
+    @recursion_trail.pop
+    result
+  end
+
+  def deja_vu?(current_place)
+    @recursion_trail.any? { |previous_place| previous_place == current_place }
+  end
+
+  # #=== allows us to rely on Module implementing #=== instead of relying on the
+  # thing (which could be any kind of wacky object) having to implement
+  # #is_a? or #kind_of?
+  def output(thing)
+    if deja_vu?(thing)
+      output_deja_vu(thing)
+    elsif Hash === thing
+      output_hash(thing)
+    elsif Array === thing
+      output_array(thing)
+    else
+      output_unknown(thing)
+    end
+  end
+
+  HASH_OPEN = "{".freeze
+  HASH_CLOSE = "}".freeze
+  HASHROCKET = "=>".freeze
+  COLON = ":".freeze
+
+  def output_hash(hash)
+    @output << @indent unless this_indent_should_be_skipped
+
+    @output << HASH_OPEN
+    @output << NEWLINE
+
+    increase_indentation
+    track_recursion(hash) do
+      hash.each do |key, value|
+        @output << @indent
+
+        if key.is_a?(Symbol)
+          @output << key
+          @output << COLON
+          @output << SPACE
+        else
+          @output << ::Specdiff.diff_inspect(key)
+          @output << SPACE
+          @output << HASHROCKET
+          @output << SPACE
+        end
+
+        skip_next_opening_indent
+        output(value)
+
+        @output << COMMA
+        @output << NEWLINE
+      end
+    end
+    decrease_indentation
+
+    @output << @indent
+    @output << HASH_CLOSE
+  end
+
+  ARRAY_OPEN = "[".freeze
+  ARRAY_CLOSE = "]".freeze
+
+  def output_array(array)
+    @output << @indent unless this_indent_should_be_skipped
+
+    @output << ARRAY_OPEN
+    @output << NEWLINE
+
+    increase_indentation
+    track_recursion(array) do
+      array.each do |element|
+        output(element)
+        @output << COMMA
+        @output << NEWLINE
+      end
+    end
+    decrease_indentation
+
+    @output << @indent
+    @output << ARRAY_CLOSE
+  end
+
+  def output_unknown(thing)
+    @output << @indent unless this_indent_should_be_skipped
+
+    @output << ::Specdiff.diff_inspect(thing)
+  end
+
+  # The stdlib inspect code returns this when you have recursive structures.
+  STANDARD_INSPECT_RECURSIVE_ARRAY = "[...]".freeze
+  STANDARD_INSPECT_RECURSIVE_HASH = "{...}".freeze
+
+  def output_deja_vu(thing)
+    @output << @indent unless this_indent_should_be_skipped
+
+    case thing
+    when Array
+      # "#<Array ##{thing.object_id}>"
+      @output << STANDARD_INSPECT_RECURSIVE_ARRAY
+    when Hash
+      # "#<Hash ##{thing.object_id}>"
+      @output << STANDARD_INSPECT_RECURSIVE_HASH
+    else
+      # this should never happen
+      raise "Specdiff::Hashprint missing deja vu for: #{thing.inspect}"
+    end
+  end
+end