check_please 0.1.0 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9e2ff8cbe19131bcf4995eb057ef566bc8f4f102e138d7db5dc908befa1fbcf
-  data.tar.gz: 616388b3ee563b7f384b7fc19b051117c0f83bd00e47092f7f6f7b9ec712c81b
+  metadata.gz: c4433e70c9c7da92bbc95c1bfb2f22a947be4e3d30c9fa5b1d735826cc45dde1
+  data.tar.gz: 249804476d1b19c1f9add240b20f5e05b9258d4a70f992b5bc8a3654339e7f5c
 SHA512:
-  metadata.gz: f4b7bcef1fda2618631f59fe8ad17a2630ba33271a2c6e295b96f204076c29ba283b3bb19cfba1c8550cc03ecd709fd1aa9ecbf22db4846d3d1f7b302b7c4ee5
-  data.tar.gz: 18be8f0813b99bb66930ceb5dc2b658b377522c84d77ed3361daaecfc1aaff08f439582bb0e63056e8f8617239379c25ed44b8a517d7d8eaf92834b616d77267
+  metadata.gz: be7a4320ecb7bf5836ed62ed629e3445b20e2e847e497847a5cdbab856694b46b7f039e8c423622b0b35f5d098398c1f060655e9f4f11aacc2b15adeeb1dda61
+  data.tar.gz: e15695cfa60a8c2cf29b54b32c33ce76a5758fe76cd8ac92cb90b362d1597060de469b99c4a2e182a5b35b28b4d1757508b6e8b058a6371fd7455ad2a30d7ae3

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    check_please (0.1.0)
+    check_please (0.2.4)
       table_print
 
 GEM

data/README.md

@@ -1,6 +1,7 @@
-# CheckPlease
+# check_please
 
-Check for differences between two JSON strings (or Ruby data structures parsed from them).
+Check for differences between two JSON documents, YAML documents, or Ruby data
+structures parsed from either of those.
 
 ## Installation
 
@@ -18,29 +19,147 @@ Or install it yourself as:
 
     $ gem install check_please
 
+## Terminology
+
+I know, you just want to see how to use this thing.  Feel free to scroll down,
+but be aware that CheckPlease uses a few words in a jargony way:
+
+* **Reference** is always used to refer to the "target" or "source of truth."
+  We assume you're comparing two things because you want one of them to be like
+  the other; the **reference** is what you're aiming for.
+* **Candidate** is always used to refer to some JSON you'd like to compare
+  against the **reference**.  _(We could've also used "sample," but it turns
+  out that "reference" and "candidate" are the same length, which makes code
+  line up neatly in a monospaced font...)_
+* A **diff** is what CheckPlease calls an individual discrepancy between the
+  **reference** and the **candidate**.  More on this in "Understanding the Output",
+  below.
+
 ## Usage
 
-### CLI
+### From the Terminal
 
 Use the `bin/check_please` executable.  (To get started, run it with the '-h' flag.)
 
-### From Within Ruby
+Note that the executable assumes you've saved your **reference** to a file.
+Once that's done, you can either save the **candidate** to a file as well if
+that fits your workflow, **or** you can pipe it to `bin/check_please` in lieu
+of giving it a second filename as the argument.  (This is especially useful if
+you're copying an XHR response out of a web browser's dev tools and have a tool
+like MacOS's `pbpaste` utility.)
+
+### From RSpec
+
+See [check_please_rspec_matcher](https://github.com/RealGeeks/check_please_rspec_matcher).
+
+### From Ruby
+
+Create two strings, each containing a JSON or YAML document, and pass them to
+`CheckPlease.render_diff`.  You'll get back a third string containing a report
+of all the differences CheckPlease found in the two JSON strings.  (See also:
+[./usage_examples.rb](usage_examples.rb).)
+
+### Understanding the Output
+
+CheckPlease follows the Unix philosophy of "no news is good news".  If your
+**candidate** matches your **reference**, you'll get an empty message.
+
+But let's be honest:  how often is that going to happen?  No, you're using this
+tool because you want a human-friendly summary of all the places that your
+**candidate** fell short.
+
+When CheckPlease compares your two samples, it generates a list of diffs to
+describe any discrepancies it encounters.
+
+An example would probably help here.
+
+_(NOTE: these examples may fall out of date with the code.  They're swiped
+from [the CLI integration spec](spec/cli_integration_spec.rb), so please
+consider that more authoritative than this README.  If you do spot a
+difference, please feel free to open an issue!)_
+
+Given the following **reference** JSON:
+```
+{
+  "id": 42,
+  "name": "The Answer",
+  "words": [ "what", "do", "you", "get", "when", "you", "multiply", "six", "by", "nine" ],
+  "meta": { "foo": "spam", "bar": "eggs", "yak": "bacon" }
+}
+```
+
+And the following **candidate** JSON:
+```
+{
+  "id": 42,
+  "name": [ "I am large, and contain multitudes." ],
+  "words": [ "what", "do", "we", "get", "when", "I", "multiply", "six", "by", "nine", "dude" ],
+  "meta": { "foo": "foo", "yak": "bacon" }
+}
+```
+
+CheckPlease should produce the following output:
+
+```
+TYPE          | PATH      | REFERENCE  | CANDIDATE
+--------------|-----------|------------|-------------------------------
+type_mismatch | /name     | The Answer | ["I am large, and contain m...
+mismatch      | /words/3  | you        | we
+mismatch      | /words/6  | you        | I
+extra         | /words/11 |            | dude
+missing       | /meta/bar | eggs       |
+mismatch      | /meta/foo | spam       | foo
+```
+
+Let's start with the leftmost column...
+
+#### Diff Types
+
+The above example is intended to illustrate every possible type of diff that
+CheckPlease defines:
+
+* **type_mismatch** means that both the **reference** and the **candidate** had
+  a value at the given path, but one value was an Array or a Hash and the other
+  was not.  **When CheckPlease encounters a type mismatch, it does not compare
+  anything "below" the given path.**  _(Technical note:  CheckPlease uses a
+  "recursive descent" strategy to traverse the **reference** data structure,
+  and it stops when it encounters a type mismatch in order to avoid producing a
+  lot of "garbage" diff output.)_
+* **mismatch** means that both the **reference** and the **candidate** had a
+  value at the given path, and neither value was an Array or a Hash.
+* **extra** means that, inside an Array or a Hash, the **candidate** contained
+  values that were not found in the **reference**.
+* **missing** is the opposite of **extra**:  inside an Array or a Hash, the
+  **reference** contained values that were not found in the **candidate**.
+
+#### Paths
+
+The second column contains a path expression.  This is extremely lo-fi:
+
+* The root of the data structure is defined as "/".
+* If an element in the data structure is an array, its child elements will have
+  a **one-based** index appended to their parent's path.
+* If an element in the data structure is an object ("Hash" in Ruby), the key
+  for each element will be appended to their parent's path, and the values will
+  be compared.
+
+_**Being primarily a Ruby developer, I'm quite ignorant of conventions in the
+JS community; if there's an existing convention for paths, please open an
+issue!**_
+
+#### Output Formats
 
-Create two JSON strings and pass them to `CheckPlease.render_diff`.  You'll get
-back a third string containing a nicely formatted report of all the differences
-CheckPlease found in the two JSON strings.  (See also:  ./usage_examples.rb.)
+CheckPlease produces tabular output by default.  (It leans heavily on the
+amazing [table_print](http://tableprintgem.com) gem for this.)
 
-(You can also parse the JSON strings yourself and pass the resulting data
-structures in, if you're into that.  I mean, I wrote this to help compare JSON
-data that's too big and complicated to scan through visually, but you do you!
+If you want to incorporate CheckPlease into some other toolchain, it can also
+print diffs as JSON to facilitate parsing.  In Ruby, pass `format: :json` to
+`CheckPlease.render_diff`; in the CLI, use the `-f`/`--format` switch.
 
 ## TODO
 
-* rspec custom matcher (separate gem?)
 * command line flags for :allthethings:!
-  * limit to first N
   * sort by path?
-  * max depth (for iterative refinement?)
 * detect timestamps and compare after parsing?
   * ignore sub-second precision (option / CLI flag)?
   * possibly support plugins for other folks to add custom coercions?

data/Rakefile

@@ -1,6 +1,21 @@
 require "bundler/gem_tasks"
 require "rspec/core/rake_task"
 
-RSpec::Core::RakeTask.new(:spec)
+namespace :spec do
+  RSpec::Core::RakeTask.new(:all)
+
+  RSpec::Core::RakeTask.new(:not_cli) do |t|
+    t.rspec_opts = "--tag ~cli"
+  end
+  task fast: :not_cli
+
+  # These are much slower than the rest, since they use Kernel#`
+  RSpec::Core::RakeTask.new(:cli) do |t|
+    t.rspec_opts = "--tag cli"
+  end
+end
+
+# By default, `rake spec` should run fast specs first, then cli if those all pass
+task :spec => [ "spec:not_cli", "spec:cli" ]
 
 task :default => :spec

data/exe/check_please

@@ -0,0 +1,4 @@
+#!/usr/bin/env ruby
+
+require 'check_please'
+CheckPlease::CLI.run(__FILE__)

data/lib/check_please.rb

@@ -1,38 +1,44 @@
 require_relative "check_please/version"
+require_relative "check_please/error"
 require_relative "check_please/path"
 require_relative "check_please/comparison"
 require_relative "check_please/diff"
 require_relative "check_please/diffs"
 require_relative "check_please/printers"
+require_relative "check_please/cli"
+
+require 'yaml'
+require 'json'
 
 module CheckPlease
-  class Error < StandardError; end
+  ELEVATOR_PITCH = "Tool for parsing and diffing two JSON documents."
 
-  def self.diff(reference, candidate)
+  def self.diff(reference, candidate, options = {})
     reference = maybe_parse(reference)
     candidate = maybe_parse(candidate)
-    Comparison.perform(reference, candidate)
+    Comparison.perform(reference, candidate, options)
   end
 
-  def self.render_diff(reference, candidate, format: nil)
-    diffs = diff(reference, candidate)
-    Printers.render(diffs, format)
+  def self.render_diff(reference, candidate, options = {})
+    diffs = diff(reference, candidate, options)
+    Printers.render(diffs, options)
   end
 
   class << self
     private
 
     # Maybe you gave us JSON strings, maybe you gave us Ruby objects.
-    # We just don't know!  That's what makes it so exciting!
-    def maybe_parse(maybe_json)
+    # Heck, maybe you even gave us some YAML!  We just don't know!
+    # That's what makes it so exciting!
+    def maybe_parse(document)
 
-      case maybe_json
-      when String ; JSON.parse(maybe_json) # don't worry, if this raises we'll assume you've already parsed it
-      else        ; maybe_json
+      case document
+      when String ; return YAML.load(document) # don't worry, if this raises we'll assume you've already parsed it
+      else        ; return document
       end
 
-    rescue JSON::ParserError
-      return maybe_json
+    rescue JSON::ParserError, Psych::SyntaxError
+      return document
     end
   end
 end

data/lib/check_please/cli.rb

@@ -0,0 +1,45 @@
+require_relative 'cli/flag'
+# require_relative 'cli/flags'
+require_relative 'cli/parser'
+require_relative 'cli/runner'
+
+module CheckPlease
+
+  module CLI
+    def self.run(exe_file_name)
+      Runner.new(__FILE__).run(*ARGV.dup)
+    end
+
+
+
+    FLAGS = []
+    def self.flag(long:, short: nil, &block)
+      flag = Flag.new(short, long, &block)
+      FLAGS << flag
+    end
+
+    ##### Define CLI flags here #####
+
+    flag short: "-f FORMAT", long: "--format FORMAT" do |f|
+      f.desc = "format in which to present diffs (available options: [#{CheckPlease::Printers::FORMATS.join(", ")}])"
+      f.set_key :format, :to_sym
+    end
+
+    flag short: "-n MAX_DIFFS", long: "--max-diffs MAX_DIFFS" do |f|
+      f.desc = "Stop after encountering a specified number of diffs"
+      f.set_key :max_diffs, :to_i
+    end
+
+    flag long: "--fail-fast" do |f|
+      f.desc = "Stop after encountering the very first diff"
+      f.set_key(:max_diffs) { 1 }
+    end
+
+    flag short: "-d MAX_DEPTH", long: "--max-depth MAX_DEPTH" do |f|
+      f.desc = "Limit the number of levels to descend when comparing documents (NOTE: root has depth=1)"
+      f.set_key :max_depth, :to_i
+    end
+
+  end
+
+end

data/lib/check_please/cli/flag.rb

@@ -0,0 +1,40 @@
+module CheckPlease
+module CLI
+
+  class Flag
+    ATTR_NAMES = %i[ short long desc key block ]
+    attr_accessor(*ATTR_NAMES)
+
+    def initialize(*args)
+      self.short = args.shift if args.any?
+      self.long  = args.shift if args.any?
+
+      yield self if block_given?
+
+      missing = ATTR_NAMES.select { |e| self.send(e).nil? }
+      missing -= %i[ short ] # short is optional!
+      if missing.any?
+        raise ArgumentError, "Missing attributes: #{missing.join(', ')}"
+      end
+    end
+
+    def visit_option_parser(parser, options)
+      parser.on(short, long, desc) do |value|
+        block.call options, value
+      end
+    end
+
+    def set_key(key, message = nil, &b)
+      raise ArgumentError if message && b
+      raise ArgumentError if !message && !b
+
+      self.key = key
+      self.block = ->(options, value) {
+        b ||= message.to_sym.to_proc
+        options[key] = b.call(value)
+      }
+    end
+  end
+
+end
+end

data/lib/check_please/cli/parser.rb

@@ -0,0 +1,58 @@
+require 'optparse'
+
+module CheckPlease
+module CLI
+
+  class Parser
+    class UnrecognizedOption < StandardError
+      include CheckPlease::Error
+    end
+
+    def initialize(exe_file_name)
+      @exe_file_name = exe_file_name
+      @optparse = OptionParser.new
+      @optparse.banner = banner
+
+      @options = {} # yuck
+      CheckPlease::CLI::FLAGS.each do |flag|
+        flag.visit_option_parser(@optparse, @options)
+      end
+    end
+
+    # Unfortunately, OptionParser *really* wants to use closures.
+    # I haven't yet figured out how to get around this...
+    def consume_flags!(args)
+      @optparse.parse!(args) # removes recognized flags from `args`
+      return @options
+    rescue OptionParser::InvalidOption, OptionParser::AmbiguousOption => e
+      raise UnrecognizedOption, e.message, cause: e
+    end
+
+    def help
+      @optparse.help
+    end
+
+    private
+
+    def banner
+      <<~EOF
+        Usage: #{@exe_file_name} <reference> <candidate> [FLAGS]
+
+          #{CheckPlease::ELEVATOR_PITCH}
+
+          Arguments:
+            <reference> is the name of a file to use as, well, the reference.
+            <candidate> is the name of a file to compare against the reference.
+
+            NOTE: If you have a utility like MacOS's `pbpaste`, you MAY omit
+            the <candidate> arg, and pipe the second document instead, like:
+
+              $ pbpaste | #{@exe_file_name} <reference>
+
+          FLAGS:
+      EOF
+    end
+  end
+
+end
+end

data/lib/check_please/cli/runner.rb

@@ -0,0 +1,79 @@
+module CheckPlease
+module CLI
+
+  class Runner
+    def initialize(exe_file_name)
+      @parser = Parser.new(exe_file_name)
+    end
+
+    # NOTE: unusually for me, I'm using Ruby's `or` keyword in this method.
+    # `or` short circuits just like `||`, but has lower precedence, which
+    # enables some shenanigans...
+    def run(*args)
+      args.flatten!
+      print_help_and_exit if args.empty?
+
+      begin
+        options = @parser.consume_flags!(args)
+      rescue Parser::UnrecognizedOption => e
+        print_help_and_exit e.message
+      end
+
+      # The reference MUST be the first arg...
+      reference = \
+        read_file(args.shift) \
+        or print_help_and_exit "Missing <reference> argument"
+
+      # The candidate MAY be the second arg, or it might have been piped in...
+      candidate = \
+        read_file(args.shift) \
+        || read_piped_stdin \
+        or print_help_and_exit "Missing <candidate> argument, AND nothing was piped in"
+
+      # Looks like we're good to go!
+      diff_view = CheckPlease.render_diff(reference, candidate, options)
+      puts diff_view
+    end
+
+
+
+    private
+
+    def print_help_and_exit(message = nil)
+      puts "\n>>> #{message}\n\n" if message
+      puts @parser.help
+      exit
+    end
+
+    def read_file(filename)
+      return nil if filename.nil?
+      File.read(filename)
+    rescue Errno::ENOENT
+      return nil
+    end
+
+    # Unfortunately, ARGF won't help us here because it doesn't seem to want to
+    # read from stdin after it's already pulled a file out of ARGV.  So, we
+    # have to read from stdin ourselves.
+    #
+    # BUT THAT'S NOT ALL!  If the user didn't actually pipe any data,
+    # $stdin.read will block until they manually send EOF or hit Ctrl+C.
+    #
+    # Fortunately, we can detect whether $stdin.read will block by checking to
+    # see if it is a TTY.  (Wait, what century is this again?)
+    #
+    # For fun and posterity, here's an experiment you can use to demonstrate this:
+    #
+    #   $ ruby -e 'puts $stdin.tty? ? "YES YOU ARE A TTY" : "nope, no tty here"'
+    #   YES YOU ARE A TTY
+    #
+    #   $ cat foo | ruby -e 'puts $stdin.tty? ? "YES YOU ARE A TTY" : "nope, no tty here"'
+    #   nope, no tty here
+    def read_piped_stdin
+      return nil if $stdin.tty?
+      return $stdin.read
+    end
+  end
+
+end
+end

data/lib/check_please/comparison.rb

@@ -3,16 +3,22 @@ module CheckPlease
   module Comparison
     extend self
 
-    def perform(reference, candidate)
+    def perform(reference, candidate, options = {})
       root = CheckPlease::Path.new
-      diffs = Diffs.new
-      compare reference, candidate, root, diffs
+      diffs = Diffs.new(options: options)
+      catch(:max_diffs_reached) do
+        compare reference, candidate, root, diffs
+      end
       diffs
     end
 
     private
 
     def compare(ref, can, path, diffs)
+      if (d = diffs.options[:max_depth])
+        return if path.depth > d + 1
+      end
+
       case types(ref, can)
       when [ :array, :array ] ; compare_arrays ref, can, path, diffs
       when [ :hash,  :hash  ] ; compare_hashes ref, can, path, diffs

data/lib/check_please/diffs.rb

@@ -5,7 +5,9 @@ module CheckPlease
   # Custom collection class for Diff instances.
   # Can retrieve members using indexes or paths.
   class Diffs
-    def initialize(diff_list = nil)
+    attr_reader :options
+    def initialize(diff_list = nil, options: {})
+      @options = options
       @list = []
       @hash = {}
       Array(diff_list).each do |diff|
@@ -27,6 +29,11 @@ module CheckPlease
     end
 
     def <<(diff)
+      if (n = options[:max_diffs])
+        # It seems no one can help me now / I'm in too deep, there's no way out
+        throw :max_diffs_reached if length >= n
+      end
+
       @list << diff
       @hash[diff.path] = diff
     end

data/lib/check_please/error.rb

@@ -0,0 +1,9 @@
+module CheckPlease
+
+  module Error
+    # Rather than having a common error superclass, I'm taking a cue from
+    # https://avdi.codes/exceptionalruby and tagging things with a module
+    # instead....
+  end
+
+end

data/lib/check_please/path.rb

@@ -11,6 +11,10 @@ module CheckPlease
       self.class.new( Array(@segments) + Array(new_basename.to_s) )
     end
 
+    def depth
+      1 + @segments.length
+    end
+
     def to_s
       SEPARATOR + @segments.join(SEPARATOR)
     end

data/lib/check_please/printers.rb

@@ -12,8 +12,8 @@ module CheckPlease
     FORMATS = PRINTERS_BY_FORMAT.keys.sort
     DEFAULT_FORMAT = :table
 
-    def self.render(diffs, format)
-      format ||= DEFAULT_FORMAT
+    def self.render(diffs, options = {})
+      format = options[:format] || DEFAULT_FORMAT
       printer = PRINTERS_BY_FORMAT[format.to_sym]
       printer.render(diffs)
     end

data/lib/check_please/printers/json.rb

@@ -1,5 +1,3 @@
-require 'json'
-
 module CheckPlease
 module Printers
 

data/lib/check_please/printers/table_print.rb

@@ -14,11 +14,12 @@ module Printers
     def to_s
       return "" if diffs.empty?
 
-      build_string do |io|
+      out = build_string do |io|
         switch_tableprint_io(io) do
           tp diffs.data, *TP_OPTS
         end
       end
+      strip_trailing_whitespace(out)
     end
 
     private
@@ -31,6 +32,10 @@ module Printers
     ensure
       config.io = @old_io
     end
+
+    def strip_trailing_whitespace(s)
+      s.lines.map(&:rstrip).join("\n")
+    end
   end
 
 end

data/lib/check_please/version.rb

@@ -1,3 +1,5 @@
 module CheckPlease
-  VERSION = "0.1.0"
+  # NOTE: 'check_please_rspec_matcher' depends on this,
+  #       so try to keep them roughly in sync
+  VERSION = "0.2.4"
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: check_please
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.4
 platform: ruby
 authors:
 - Sam Livingston-Gray
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-11-06 00:00:00.000000000 Z
+date: 2020-11-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: table_print
@@ -56,7 +56,8 @@ description: Check for differences between two JSON strings (or Ruby data struct
   parsed from them)
 email:
 - geeksam@gmail.com
-executables: []
+executables:
+- check_please
 extensions: []
 extra_rdoc_files: []
 files:
@@ -69,14 +70,19 @@ files:
 - LICENSE.txt
 - README.md
 - Rakefile
-- bin/check_please
 - bin/console
 - bin/setup
 - check_please.gemspec
+- exe/check_please
 - lib/check_please.rb
+- lib/check_please/cli.rb
+- lib/check_please/cli/flag.rb
+- lib/check_please/cli/parser.rb
+- lib/check_please/cli/runner.rb
 - lib/check_please/comparison.rb
 - lib/check_please/diff.rb
 - lib/check_please/diffs.rb
+- lib/check_please/error.rb
 - lib/check_please/path.rb
 - lib/check_please/printers.rb
 - lib/check_please/printers/base.rb

data/bin/check_please

@@ -1,70 +0,0 @@
-#!/usr/bin/env ruby
-
-require 'optparse'
-
-require_relative '../lib/check_please'
-
-argv = ARGV.dup
-
-ref_file = argv.shift
-can_file = argv.shift
-diff_opts = {}
-
-@parser = OptionParser.new do |opts|
-  opts.banner = <<~EOF
-Usage: #{__FILE__} <reference> <candidate> <options>
-
-  Tool for parsing and diffing two JSON files.
-
-  Arguments:
-    <reference> is the name of a file to use as the reference.
-    <candidate> is the name of a file to compare against the reference.
-
-    NOTE:  If the <candidate> arg is omitted, stdin will be used instead.
-    This allows you to copy candidate JSON to the clipboard and (on a Mac) do:
-
-      $ pbpaste | #{__FILE__} <reference>
-
-  <options>:
-	EOF
-
-  formats = CheckPlease::Printers::FORMATS.join(", ")
-
-  opts.on("-f FORMAT", "--format FORMAT", "specify the format (available options: [#{formats}]") do |val|
-    diff_opts[:format] = val
-  end
-end
-
-
-
-def print_help_and_exit
-  @parser.parse(%w[--help])
-  exit # technically redundant but helps me feel better
-end
-
-def read_file(filename)
-  return nil if filename.to_s =~ /^\s*$/
-  File.read(filename)
-rescue Errno::ENOENT
-  # no such file, buddy
-  return nil
-end
-
-
-
-# First off, try to read in the files the user told us about...
-reference = read_file(ref_file)
-candidate = read_file(can_file) || $stdin.read
-
-print_help_and_exit if reference.to_s =~ /^\s*$/
-print_help_and_exit if candidate.to_s =~ /^\s*$/
-
-begin
-  @parser.parse(argv)
-rescue OptionParser::InvalidOption, OptionParser::AmbiguousOption => e
-  puts "\n>>> #{e.message}\n\n"
-  print_help_and_exit
-end
-
-report = CheckPlease.render_diff(reference, candidate, **diff_opts)
-puts report