specdiff 0.1.1 → 0.3.0.pre.rc1

data/examples/rspec/spec/spec_helper.rb

@@ -0,0 +1,68 @@
+Bundler.require
+require "specdiff/rspec"
+
+RSpec.configure do |config|
+  # rspec-expectations config goes here. You can use an alternate
+  # assertion/expectation library such as wrong or the stdlib/minitest
+  # assertions if you prefer.
+  config.expect_with :rspec do |expectations|
+    # This option will default to `true` in RSpec 4. It makes the `description`
+    # and `failure_message` of custom matchers include text for helper methods
+    # defined using `chain`, e.g.:
+    #     be_bigger_than(2).and_smaller_than(4).description
+    #     # => "be bigger than 2 and smaller than 4"
+    # ...rather than:
+    #     # => "be bigger than 2"
+    expectations.include_chain_clauses_in_custom_matcher_descriptions = true
+
+    expectations.syntax = :expect
+  end
+
+  # rspec-mocks config goes here. You can use an alternate test double
+  # library (such as bogus or mocha) by changing the `mock_with` option here.
+  config.mock_with :rspec do |mocks|
+    # Prevents you from mocking or stubbing a method that does not exist on
+    # a real object. This is generally recommended, and will default to
+    # `true` in RSpec 4.
+    mocks.verify_partial_doubles = true
+  end
+
+  # This option will default to `:apply_to_host_groups` in RSpec 4 (and will
+  # have no way to turn it off -- the option exists only for backwards
+  # compatibility in RSpec 3). It causes shared context metadata to be
+  # inherited by the metadata hash of host groups and examples, rather than
+  # triggering implicit auto-inclusion in groups with matching metadata.
+  config.shared_context_metadata_behavior = :apply_to_host_groups
+
+  # enable test focusing
+  config.filter_run_when_matching :focus
+
+  # Enable flags like --only-failures and --next-failure
+  config.example_status_persistence_file_path = ".rspec_status"
+
+  # Limits the available syntax to the non-monkey patched syntax that is
+  # recommended. For more details, see:
+  # https://rspec.info/features/3-12/rspec-core/configuration/zero-monkey-patching-mode/
+  config.disable_monkey_patching!
+
+  # This setting enables warnings. It's recommended, but in some cases may
+  # be too noisy due to issues in dependencies.
+  config.warnings = true
+
+  # Many RSpec users commonly either run the entire suite or an individual
+  # file, and it's useful to allow more verbose output when running an
+  # individual spec file.
+  if config.files_to_run.one?
+    # Use the documentation formatter for detailed output,
+    # unless a formatter has already been configured
+    # (e.g. via a command-line flag).
+    config.default_formatter = "doc"
+  end
+end
+
+class MyBasicObjectClass < BasicObject
+end
+
+class ConstantForTheSolePurposeOfUndefiningInspect
+  undef_method :inspect
+end

data/examples/webmock/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: ../..
   specs:
-    specdiff (0.1.0)
+    specdiff (0.3.0.pre.rc1)
       diff-lcs (~> 1.5)
       hashdiff (~> 1.0)
 
@@ -12,7 +12,7 @@ GEM
       public_suffix (>= 2.0.2, < 6.0)
     crack (0.4.5)
       rexml
-    diff-lcs (1.5.0)
+    diff-lcs (1.5.1)
     domain_name (0.6.20231109)
     ffi (1.16.3)
     ffi-compiler (1.0.1)

data/glossary.txt

@@ -1,3 +1,8 @@
+"raw diff"
+  the return value from a differ or plugin's #diff method
+  this can be anything, from an array of arrays (hashdiff) to a string with a
+  git diff inside
+
 diff
   the return value from the Specdiff::diff method.
   this is not the direct return value from a plugin/differ, that is the
@@ -8,17 +13,34 @@ differ
   human-comprehensible diff output for your terminal
 
 plugin
-  external differ (responding to more methods), able to be provided by third
-  parties or end users themselves
+  external differ (has to respond to more methods)
+  may be provided from outside the gem (for example by a user drowning in xml)
+
+"built in differ"
+  differ living in the specdiff/differ directory
+
+"built in plugin"
+  plugin shipped with the gem, but needs to be loaded using Specdiff.load!
 
 type
   a symbol like :text, :json or :hash which denotes the type of data in a way
   which is useful for picking a differ
 
+  a plugin returns a type from its #id method
+
   :text
     a string which likely contains plaintext data of some kind
 
+"plugin type"
+  a type added by loading a plugin (not built into specdiff)
+
 side
-  an object containing either side of a comparison that needs to be made
-  when defining a plugin, the diff method receives two sides: a, b
-  most importantly, a side contains a value and a type
+  an object containing a value and a type
+
+  used to represent the two sides to a comparison
+
+  when defining a plugin, you receive two sides: a and b, to various methods
+
+compare
+  the procedure that implements the main function of specdiff including
+  accounting for any plugin types and differs

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

@@ -0,0 +1,95 @@
+class Specdiff::Compare
+  Side = Struct.new(:value, :type, keyword_init: true)
+
+  def self.call(...)
+    new.call(...)
+  end
+
+  def call(raw_a, raw_b)
+    a = parse_side(raw_a)
+    b = parse_side(raw_b)
+
+    if a.type == :text && b.type == :binary
+      new_b = try_reencode(b.value, a.value.encoding)
+      if new_b
+        b = b.dup
+        b.type = :text
+        b.value = new_b
+      end
+    elsif a.type == :binary && b.type == :text
+      new_a = try_reencode(a.value, b.value.encoding)
+      if new_a
+        a = a.dup
+        a.type = :text
+        a.value = new_a
+      end
+    end
+
+    differ = pick_differ(a, b)
+    raw = differ.diff(a, b)
+
+    if raw.is_a?(::Specdiff::Diff) # detect recursive plugins, such as json
+      raw
+    else
+      ::Specdiff::Diff.new(raw: raw, differ: differ, a: a, b: b)
+    end
+  end
+
+private
+
+  def parse_side(raw_value)
+    type = detect_type(raw_value)
+
+    Side.new(value: raw_value, type: type)
+  end
+
+  def detect_type(thing)
+    if (type = detect_plugin_types(thing))
+      type
+    elsif thing.is_a?(Hash)
+      :hash
+    elsif thing.is_a?(Array)
+      :array
+    elsif thing.is_a?(String) && thing.encoding == Encoding::BINARY
+      :binary
+    elsif thing.is_a?(String)
+      :text
+    elsif thing.nil?
+      :nil
+    else
+      :unknown
+    end
+  end
+
+  def detect_plugin_types(thing)
+    Specdiff.plugins
+      .filter { |plugin| plugin.respond_to?(:detect_type) }
+      .detect { |plugin| plugin.detect_type(thing) }
+      &.id
+  end
+
+  def try_reencode(binary_string, target_encoding)
+    binary_string.encode(target_encoding)
+  rescue StandardError
+    nil
+  end
+
+  def pick_differ(a, b)
+    if (differ = pick_plugin_differ(a, b))
+      differ
+    elsif a.type == :text && b.type == :text
+      Specdiff::Differ::Text
+    elsif a.type == :hash && b.type == :hash
+      Specdiff::Differ::Hashdiff
+    elsif a.type == :array && b.type == :array
+      Specdiff::Differ::Hashdiff
+    else
+      Specdiff::Differ::NotFound
+    end
+  end
+
+  def pick_plugin_differ(a, b)
+    Specdiff.plugins
+      .detect { |plugin| plugin.compatible?(a, b) }
+  end
+end

data/lib/specdiff/config.rb

@@ -5,23 +5,26 @@ module Specdiff
     end
   end
 
-  # Read the configuration
-  def self.config
-    threadlocal[:config] ||= default_configuration
+  class << self
+    attr_reader :config
   end
 
+  DEFAULT = Config.new(colorize: true).freeze
+  @config = DEFAULT.dup
+
   # private, used for testing
   def self._set_config(new_config)
-    threadlocal[:config] = new_config
+    @config = new_config
   end
 
   # Set the configuration
   def self.configure
-    yield(config)
+    yield(@config)
+    @config
   end
 
   # Generates the default configuration
   def self.default_configuration
-    Config.new(colorize: true)
+    DEFAULT
   end
 end

data/lib/specdiff/diff.rb

@@ -21,8 +21,10 @@
   def inspect
     if empty?
       "<Specdiff::Diff (empty)>"
-    else
+    elsif raw.respond_to?(:bytesize)
       "<Specdiff::Diff w/ #{raw&.bytesize || 0} bytes of #raw diff>"
+    else
+      "<Specdiff::Diff #{raw.inspect}>"
     end
   end
 end

data/lib/specdiff/differ/hashdiff.rb

@@ -1,20 +1,69 @@
 require "hashdiff"
-require "pp"
 
 class Specdiff::Differ::Hashdiff
   extend ::Specdiff::Colorize
 
+  VALUE_CHANGE_PERCENTAGE_THRESHOLD = 0.2
+  TOTAL_CHANGES_FOR_GROUPING_THRESHOLD = 9
+
+  NEWLINE = "\n"
+
   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 = ::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 >= VALUE_CHANGE_PERCENTAGE_THRESHOLD
+      hashdiff_diff
+    else
+      a_text = ::Specdiff.hashprint(a.value)
+      b_text = ::Specdiff.hashprint(b.value)
+
+      diff = ::Specdiff.diff(a_text, b_text)
+
+      if diff.empty?
+        []
+      else
+        diff.a.type = a.type
+        diff.b.type = b.type
+
+        diff
+      end
+    end
+  end
+
+  def self._calculate_change_percentage(hashdiff_diff)
+    value_change_count = hashdiff_diff.count { |element| element[0] == "~" }
+    addition_count = hashdiff_diff.count { |element| element[0] == "+" }
+    deletion_count = hashdiff_diff.count { |element| element[0] == "-" }
+    # puts "hashdiff_diff: #{hashdiff_diff.inspect}"
+    # puts "value_change_count: #{value_change_count.inspect}"
+    # puts "addition_count: #{addition_count.inspect}"
+    # puts "deletion_count: #{deletion_count.inspect}"
+
+    total_number_of_changes = [
+      value_change_count,
+      addition_count,
+      deletion_count,
+    ].sum
+
+    change_fraction = Rational(value_change_count, total_number_of_changes)
+    change_percentage = change_fraction.to_f
+    # puts "change_fraction: #{change_fraction.inspect}"
+    # puts "change_percentage: #{change_percentage.inspect}"
+
+    change_percentage
   end
 
   def self.empty?(diff)
@@ -22,41 +71,68 @@ class Specdiff::Differ::Hashdiff
   end
 
   def self.stringify(diff)
-    diff.raw.pretty_inspect
-
     result = +""
 
-    diff.raw.each do |change|
-      type = change[0] # the char '+', '-' or '~'
-      path = change[1] # for example key1.key2[2] (as ["key1", :key2, 2])
-      path2 = _stringify_path(path)
+    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
 
-      if type == "+"
-        value = change[2]
+    deletions = changes_grouped_by_type["-"] || []
+    additions = changes_grouped_by_type["+"] || []
+    value_changes = changes_grouped_by_type["~"] || []
 
-        result << "added #{path2} with value #{value.inspect}"
-      elsif type == "-"
-        value = change[2]
+    deletions.each do |change|
+      value = change[2]
+      path = _stringify_path(change[1])
 
-        result << "removed #{path2} with value #{value.inspect}"
-      elsif type == "~"
-        from = change[2]
-        to = change[3]
+      result << "missing key: #{path} (#{::Specdiff.diff_inspect(value)})"
+      result << NEWLINE
+    end
 
-        result << "changed #{path2} from #{from.inspect} to #{to.inspect}"
-      else
-        result << change.inspect
-      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 << "    new 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])
 
-      result << "\n"
+      from_inspected = ::Specdiff.diff_inspect(from)
+      to_inspected = ::Specdiff.diff_inspect(to)
+      result << "changed key: #{path} (#{from_inspected} -> #{to_inspected})"
+      result << NEWLINE
     end
 
     colorize_by_line(result) do |line|
-      if line.start_with?("removed")
+      if line.start_with?("missing key:")
         red(line)
-      elsif line.start_with?("added")
+      elsif line.start_with?(/\s+new key:/)
         green(line)
-      elsif line.start_with?("changed")
+      elsif line.start_with?("changed key:")
         yellow(line)
       else
         reset_color(line)

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

@@ -1,97 +1,4 @@
-class Specdiff::Differ
-  Side = Struct.new(:value, :type, keyword_init: true)
-
-  def self.call(...)
-    new.call(...)
-  end
-
-  def call(raw_a, raw_b)
-    a = parse_side(raw_a)
-    b = parse_side(raw_b)
-
-    if a.type == :text && b.type == :binary
-      new_b = try_reencode(b.value, a.value.encoding)
-      if new_b
-        b = b.dup
-        b.type = :text
-        b.value = new_b
-      end
-    elsif a.type == :binary && b.type == :text
-      new_a = try_reencode(a.value, b.value.encoding)
-      if new_a
-        a = a.dup
-        a.type = :text
-        a.value = new_a
-      end
-    end
-
-    differ = pick_differ(a, b)
-    raw = differ.diff(a, b)
-
-    if raw.is_a?(::Specdiff::Diff) # detect recursive plugins, such as json
-      raw
-    else
-      ::Specdiff::Diff.new(raw: raw, differ: differ, a: a, b: b)
-    end
-  end
-
-private
-
-  def parse_side(raw_value)
-    type = detect_type(raw_value)
-
-    Side.new(value: raw_value, type: type)
-  end
-
-  def detect_type(thing)
-    if (type = detect_plugin_types(thing))
-      type
-    elsif thing.is_a?(Hash)
-      :hash
-    elsif thing.is_a?(Array)
-      :array
-    elsif thing.is_a?(String) && thing.encoding == Encoding::BINARY
-      :binary
-    elsif thing.is_a?(String)
-      :text
-    elsif thing.nil?
-      :nil
-    else
-      :unknown
-    end
-  end
-
-  def detect_plugin_types(thing)
-    Specdiff.plugins
-      .filter { |plugin| plugin.respond_to?(:detect_type) }
-      .detect { |plugin| plugin.detect_type(thing) }
-      &.id
-  end
-
-  def try_reencode(binary_string, target_encoding)
-    binary_string.encode(target_encoding)
-  rescue StandardError
-    nil
-  end
-
-  def pick_differ(a, b)
-    if (differ = pick_plugin_differ(a, b))
-      differ
-    elsif a.type == :text && b.type == :text
-      Specdiff::Differ::Text
-    elsif a.type == :hash && b.type == :hash
-      Specdiff::Differ::Hashdiff
-    elsif a.type == :array && b.type == :array
-      Specdiff::Differ::Hashdiff
-    else
-      Specdiff::Differ::NotFound
-    end
-  end
-
-  def pick_plugin_differ(a, b)
-    Specdiff.plugins
-      .detect { |plugin| plugin.compatible?(a, b) }
-  end
+module Specdiff::Differ
 end
 
 # require only the builtin differs, plugins are optionally loaded later