check_please 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e9e2ff8cbe19131bcf4995eb057ef566bc8f4f102e138d7db5dc908befa1fbcf
-  data.tar.gz: 616388b3ee563b7f384b7fc19b051117c0f83bd00e47092f7f6f7b9ec712c81b
+  metadata.gz: 1c16110449be99d5ff509c720c4365b2fe6f176f23094784628db2de0e5f3bf9
+  data.tar.gz: b45c9d1b7dea9b4405f4ca80dbce5f04d0aec14ad50e4e919802e09b469c86c8
 SHA512:
-  metadata.gz: f4b7bcef1fda2618631f59fe8ad17a2630ba33271a2c6e295b96f204076c29ba283b3bb19cfba1c8550cc03ecd709fd1aa9ecbf22db4846d3d1f7b302b7c4ee5
-  data.tar.gz: 18be8f0813b99bb66930ceb5dc2b658b377522c84d77ed3361daaecfc1aaff08f439582bb0e63056e8f8617239379c25ed44b8a517d7d8eaf92834b616d77267
+  metadata.gz: 023b9fdd6f227f8381dfba06a82d30961adab9b2ab5a2b5a0d820c8b8697d300f59d416c801808e88e7e625720776f1cec4cf0a6f57d1eec07e6cb656881d4b8
+  data.tar.gz: eca955971798d00dd45bf5e068779aebeb33b304fe592d84534081d0068eaa981f6b765fd5c4ea9a30e7d65b2edd456ed9093c039964e3691c646e0c7d23b2b0

data/Gemfile.lock

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

data/README.md

@@ -1,4 +1,4 @@
-# CheckPlease
+# check_please
 
 Check for differences between two JSON strings (or Ruby data structures parsed from them).
 
@@ -20,24 +20,150 @@ Or install it yourself as:
 
 ## Usage
 
+### Terminology
+
+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.
+
 ### CLI
 
 Use the `bin/check_please` executable.  (To get started, run it with the '-h' flag.)
 
+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.)
+
+### RSpec Matcher
+
+See [check_please_rspec_matcher](https://github.com/RealGeeks/check_please_rspec_matcher).
+
 ### From Within Ruby
 
 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 found in the two JSON strings.  (See also:  [./usage_examples.rb](usage_examples.rb).)
 
 (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!
 
+### 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.  (By default, it prints that list in a
+tabular format, but if you want to incorporate this into another toolchain,
+CheckPlease can also print these diffs as JSON to facilitate parsing.)
+
+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.** producing a lot of "garbage" diffs.
+  _(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.
+  Also, the way these get displayed is likely to change.)_
+* **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 basic:
+
+* The first element in 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
+
+CheckPlease produces tabular output by default.  (It leans heavily on the
+amazing [table_print](http://tableprintgem.com) gem for this.)
+
+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:!
+  * --fail-fast
   * limit to first N
   * sort by path?
   * max depth (for iterative refinement?)

data/bin/check_please

@@ -1,70 +1,4 @@
 #!/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
+CheckPlease::CLI.run(__FILE__)

data/lib/check_please.rb

@@ -1,12 +1,14 @@
 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"
 
 module CheckPlease
-  class Error < StandardError; end
+  ELEVATOR_PITCH = "Tool for parsing and diffing two JSON documents."
 
   def self.diff(reference, candidate)
     reference = maybe_parse(reference)
@@ -14,9 +16,9 @@ module CheckPlease
     Comparison.perform(reference, candidate)
   end
 
-  def self.render_diff(reference, candidate, format: nil)
+  def self.render_diff(reference, candidate, options = {})
     diffs = diff(reference, candidate)
-    Printers.render(diffs, format)
+    Printers.render(diffs, options)
   end
 
   class << self

data/lib/check_please/cli.rb

@@ -0,0 +1,29 @@
+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(*args, &block)
+      flag = Flag.new(*args, &block)
+      FLAGS << flag
+    end
+
+    ##### Define CLI flags here #####
+
+    flag "-f FORMAT", "--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
+  end
+
+end

data/lib/check_please/cli/flag.rb

@@ -0,0 +1,39 @@
+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? }
+      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/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/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/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.0"
 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.0
 platform: ruby
 authors:
 - Sam Livingston-Gray
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2020-11-06 00:00:00.000000000 Z
+date: 2020-11-13 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: table_print
@@ -74,9 +74,14 @@ files:
 - bin/setup
 - check_please.gemspec
 - 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