what_weve_got_here_is_an_error_to_communicate 0.0.1 → 0.0.2

data/spec/config_spec.rb

@@ -0,0 +1,120 @@
+require 'error_to_communicate/config'
+
+RSpec.describe 'configuration', config: true do
+  # Subclassing to make it a easier to refer to, and to get a new instance
+  # (config_class.default will not be affected by changes to Config.default)
+  let(:config_class) { Class.new ErrorToCommunicate::Config }
+
+  # named blacklists
+  let(:allow_all)  { lambda { |e| false } }
+  let(:allow_none) { lambda { |e| true  } }
+
+  # named heuristics
+  let :match_all do
+    ErrorToCommunicate::Heuristic::Exception
+  end
+
+  let :match_no_method_error do
+    ErrorToCommunicate::Heuristic::NoMethodError
+  end
+
+  # helper methods
+  def yes_accept!(config, ex)
+    expect(config.accept? ex).to eq true
+  end
+
+  def no_accept!(config, ex)
+    expect(config.accept? ex).to eq false
+  end
+
+  def config_for(attrs)
+    config_class.new attrs
+  end
+
+  describe '.default' do
+    it 'is a memoized' do
+      expect(config_class.default).to equal config_class.default
+    end
+
+    it 'is an instance of Config' do
+      expect(config_class.default).to be_a_kind_of config_class
+    end
+
+    it 'uses the default heuristics and blacklist (behaviour described below)' do
+      expect(config_class.default.heuristics).to equal config_class::DEFAULT_HEURISTICS
+      expect(config_class.default.blacklist ).to equal config_class::DEFAULT_BLACKLIST
+    end
+  end
+
+  describe 'accepting an exception' do
+    it 'doesn\'t accept non-exception-looking things -- if it can\'t parse it, then we should let the default process take place (eg exception on another system)' do
+      config = config_for blacklist:  allow_all, heuristics: [match_all]
+
+      no_accept! config, nil
+      no_accept! config, "omg"
+      no_accept! config, Struct.new(:message).new('')
+      no_accept! config, Struct.new(:backtrace).new([])
+
+      yes_accept! config, Struct.new(:message, :backtrace).new('', [])
+      yes_accept! config, capture { raise }
+    end
+
+    it 'does not accept anything from its blacklist' do
+      config = config_for blacklist: allow_none, heuristics: [match_all]
+      no_accept! config, capture { raise }
+    end
+
+    it 'accepts anything not blacklisted, that it has a heuristic for' do
+      config = config_for blacklist:  allow_all, heuristics: [match_no_method_error]
+      yes_accept! config, capture { jjj() }
+      no_accept!  config, capture { raise }
+    end
+  end
+
+  describe 'finding the heuristic for an exception' do
+    it 'raises an ArgumentError if given an acception that it won\'t accept' do
+      config = config_for blacklist:  allow_none, heuristics: [match_all]
+      expect { config.heuristic_for "not an error" }
+        .to raise_error ArgumentError, /"not an error"/
+    end
+
+    it 'finds the first heuristic that is willing to accept it' do
+      config = config_for blacklist:  allow_all,
+                          heuristics: [match_no_method_error, match_all]
+      exception = capture { sdfsdfsdf() }
+      expect(config.heuristic_for exception).to     be_a_kind_of match_no_method_error
+      expect(config.heuristic_for exception).to_not be_a_kind_of match_all
+    end
+  end
+
+  describe 'The default configuration' do
+    let(:default_config) { config_class.new }
+
+    describe 'blacklist' do
+      it 'doesn\'t accept a SystemExit' do
+        system_exit = capture { exit 1 }
+        expect(default_config.accept? system_exit).to eq false
+
+        generic_exception = capture { raise }
+        expect(default_config.accept? generic_exception).to eq true
+      end
+    end
+
+    describe 'heuristics (correct selection is tested in spec/acceptance)' do
+      it 'has heuristics for WrongNumberOfArguments' do
+        expect(default_config.heuristics).to include \
+          ErrorToCommunicate::Heuristic::WrongNumberOfArguments
+      end
+
+      it 'has heuristics for NoMethodError' do
+        expect(default_config.heuristics).to include \
+          ErrorToCommunicate::Heuristic::NoMethodError
+      end
+
+      it 'has heuristics for Exception' do
+        expect(default_config.heuristics).to include \
+          ErrorToCommunicate::Heuristic::Exception
+      end
+    end
+  end
+end

data/spec/heuristic/exception_spec.rb

@@ -0,0 +1,17 @@
+require 'heuristic/spec_helper'
+
+RSpec.describe 'Heuristic for a Exception', heuristic: true do
+  def heuristic_class
+    ErrorToCommunicate::Heuristic::Exception
+  end
+
+  it 'is for every type of exception (via inheritance)' do
+    is_for! RuntimeError.new
+    is_for! Exception.new('omg')
+  end
+
+  it 'uses the exception message as is explanation' do
+    einfo = heuristic_for(message: 'message from exception')
+    expect(einfo.explanation).to eq 'message from exception'
+  end
+end

data/spec/heuristic/load_error_spec.rb

@@ -0,0 +1,195 @@
+require 'heuristic/spec_helper'
+
+RSpec.describe 'Heuristic for a LoadError', heuristic: true do
+  def heuristic_class
+    ErrorToCommunicate::Heuristic::LoadError
+  end
+
+  it 'is for LoadErrors with a message that includes " -- " to separate the message from the path' do
+    is_for! LoadError.new 'cannot load such file -- a/b/c'
+    is_for! LoadError.new "no such file to load -- /a/b/c\ndef\tghi\ejkl"
+    is_for! LoadError.new(' -- ')
+    is_not_for! LoadError.new('-- ')
+    is_not_for! LoadError.new(' --')
+    is_not_for! LoadError.new('whatever')
+    is_not_for! LoadError.new('what-ever')
+  end
+
+  describe 'methods that can lead to this error' do
+    it('works for require')          { is_for! capture { require 'a/b/c' } }
+    it('works for require_relative') { is_for! capture { require_relative 'a/b/c' } }
+    it('works for load')             { is_for! capture { load 'a/b/c' } }
+  end
+
+  describe 'identifying the missing path' do
+    def heuristic_for_path(path)
+      heuristic_for message: "cannot load such file -- #{path}"
+    end
+
+    def identifies!(path, expected=path)
+      heuristic_for_path(path).tap { |h| expect(h.path).to eq Pathname.new(expected) }
+    end
+
+    def absolute!(path)
+      heuristic = heuristic_for_path(path)
+      expect(heuristic).to     be_absolute
+      expect(heuristic).to_not be_relative
+    end
+
+    def relative!(path)
+      heuristic = heuristic_for_path(path)
+      expect(heuristic).to_not be_absolute
+      expect(heuristic).to     be_relative
+    end
+
+    it('identifies paths without directories')        { identifies! 'thepath' }
+    it('identifies paths with underscores')           { identifies! 'the_path' }
+    it('identifies paths within directories')         { identifies! 'this/is/a/path' }
+    it('identifies empty strings')                    { identifies! "" }
+    it('identifies empty space filenames')            { identifies! " " }
+    it('identifies filenames that begin with spaces') { identifies! " abc" }
+    it('identifies filenames that end with spaces')   { identifies! "abc " }
+    it('identifies paths with whitespace')            { identifies! "a b" }
+    it('identifies paths with dashes')                { identifies! 'a-b - c  -  d' }
+    it('identifies paths with double dashes')         { identifies! 'a--b -- c  --  d' }
+    it('identifies paths with escaped characters')    { identifies! 'a\nb\tc\ed' }
+    # Not sure if it should do this, or provide both the relative and absolute path
+    # it 'expands paths from the home-dir to be absolute' do
+    #   identifies! '/a/b/c', '/a/b/c'
+    #   identifies! 'a/b/c',  'a/b/c'
+    #   identifies! '~/a/b/c', "#{ENV['HOME']}/a/b/c"
+    #   identifies! '~a/b/c',  '~a/b/c'
+    # end
+  end
+
+  describe 'identification of the relevant locations from the backtrace' do
+    it 'identifies the first line that is outside of rubygems' do
+      heuristic = heuristic_for backtrace: [
+        "/a/b:1:in `a'", "/a/c:2:in `c'", "/d:3:in `d'", "/e:4:in `e'"
+      ], rubygems_dir: '/a'
+      expect(heuristic.first_nongem_line.path.to_s).to eq '/d'
+
+      heuristic = heuristic_for backtrace: [
+        "/b:2:in `b'", "/c:3:in `c'"
+      ], rubygems_dir: '/a'
+      expect(heuristic.first_nongem_line.path.to_s).to eq '/b'
+
+      heuristic = heuristic_for backtrace: [
+        "/a/b:1:in `a'", "/c:2:in `c'", "/d:3:in `d'"
+      ], rubygems_dir: '/a/b'
+      expect(heuristic.first_nongem_line.path.to_s).to eq '/c'
+
+      heuristic = heuristic_for backtrace: [
+        "/a/b:1:in `a'", "/c:2:in `c'", "/d:3:in `d'"
+      ], rubygems_dir: '/'
+      expect(heuristic.first_nongem_line).to eq nil
+    end
+
+    it 'identifies the line within the project root' do
+      heuristic = heuristic_for backtrace: [
+        "/a/b:1:in `a'", "/c:2:in `c'", "/d:3:in `d'"
+      ], root: '/a'
+      expect(heuristic.first_line_within_lib.path.to_s).to eq '/a/b'
+
+      heuristic = heuristic_for backtrace: [
+        "/a/b:1:in `a'", "/c/d:2:in `c'", "/e:3:in `e'"
+      ], root: '/c'
+      expect(heuristic.first_line_within_lib.path.to_s).to eq '/c/d'
+
+      heuristic = heuristic_for backtrace: [
+        "/a/b:1:in `a'", "/c/d:2:in `c'", "/e:3:in `e'"
+      ], root: '/x'
+      expect(heuristic.first_line_within_lib).to eq nil
+    end
+
+    specify 'when they are different, it displays them both' do
+      heuristic = heuristic_for backtrace: [
+        "/a/b:1:in `a'", "/c/d:2:in `c'", "/e:3:in `e'"
+      ], root: '/c'
+      expect(heuristic.relevant_locations.map(&:path).map(&:to_s)).to eq ['/a/b', '/c/d']
+    end
+
+    specify 'when they are the same, it only displays them once' do
+      heuristic = heuristic_for backtrace: [
+        "/a/b:1:in `a'", "/c/d:2:in `c'", "/e:3:in `e'"
+      ], root: '/a'
+      expect(heuristic.relevant_locations.map(&:path).map(&:to_s)).to eq ['/a/b']
+    end
+
+    specify 'when either is missing, it displays the other' do
+      heuristic = heuristic_for backtrace: ["/a/b:1:in `a'"], root: '/b'
+      expect(heuristic.relevant_locations.map(&:path).map(&:to_s)).to eq ['/a/b']
+    end
+
+    specify 'when both are missing, it displays a message stating this' do
+      heuristic = heuristic_for backtrace: ["/a/b:1:in `a'"],
+                                root: '/b',
+                                rubygems_dir: '/a'
+      expect(heuristic.relevant_locations).to eq []
+      name, (context, message) = heuristic.semantic_info
+      expect(name).to eq :heuristic
+      expect(context).to eq :context
+      expect(message).to be_a_kind_of String
+    end
+  end
+
+  describe 'displaying relevant code' do
+    let :semantic_code do
+      _heuristic, ((_code, code_attrs), *) =
+        heuristic_for(root:      '/a',
+                      backtrace: ["/a/b:1:in `a'"],
+                      message:   'cannot load such file -- zomg'
+                     ).semantic_info
+      expect(code_attrs[:location].path.to_s).to eq '/a/b'
+      code_attrs
+    end
+
+    # TODO: Should 5 be configurable?
+    it 'includes 5 lines of context before/after' do
+      expect(semantic_code[:context]).to eq (-5..5)
+    end
+
+    it 'emphasizes the code' do
+      expect(semantic_code[:emphasis]).to eq :code
+    end
+
+    context 'when the line includes the path' do
+      it 'has the message "Couldn\'t find file"' do
+        skip 'Waiting b/c it\'s inconvenient right now to get the code in the heuristic'
+      end
+    end
+
+    context 'when the line does not include the path' do
+      it 'has the message "Couldn\'t find \"<FILE>\""' do
+        expect(semantic_code[:message]).to eq 'Couldn\'t find "zomg"'
+      end
+    end
+  end
+
+  # Maybe eventuallly:
+  #
+  # it identifies that they are trying to require a file from a gem they don't have
+  # When the require statement is relative (require "./something")
+  #   it identifies that they could have required it if run from a different directory
+  #   it gives them the `require_relative` path
+  #   it tells them how to set up the $LOAD_PATH to avoid the need for such things
+  #   it tells them where they would need to make the file, and warns of the danger of this approach
+  # When using require_relative
+  #   it identifies misspellings in the require statement
+  #   it identifies candidate files that could be required if the path were different
+  #   it tells them where they would need to make the file
+  # When the require statement is not relative (require "something")
+  #   it identifies misspellings for files they could have required
+  #   it identifies that they meant to require something from a gem
+  #     if not using Bundler, tells them to `bundle exec` it
+  #     if using Bundler
+  #       if the gem is not part of the Gemfile, tells them how to add it
+  #       if the gem is part of the Gemfile, suggests they check versions
+  #   it tells them places they could make the file that are within their lib
+  #
+  # It could possibly look at constant names that they use after the require statement,
+  #   if any of them look sufficiently similar to the require statement,
+  #   assuming that the require statement was intended to make that constant available
+  #   if it can then identify where the constant is defined,
+  #   then it could tell them which file to require to get it.
+end

data/spec/heuristic/no_method_error_spec.rb

@@ -0,0 +1,25 @@
+require 'heuristic/spec_helper'
+
+RSpec.describe 'Heuristic for a NoMethodError', heuristic: true do
+  def heuristic_class
+    ErrorToCommunicate::Heuristic::NoMethodError
+  end
+
+  def extracts_method_name!(expected, message)
+    heuristic = heuristic_for message: message
+    expect(heuristic.undefined_method_name).to eq expected
+  end
+
+  it 'is for NoMethodErrors and NameErrors where it can parse out the missing name' do
+    is_for!     NoMethodError.new("undefined method `backtrace4' for Test:Module")
+    is_for!     NameError.new("undefined local variable or method `backtrace4' for Test:Module")
+    is_not_for! NoMethodError.new("abc")
+    is_not_for! NameError.new("abc")
+    is_not_for! Exception.new("undefined local variable or method `backtrace4' for Test:Module") # do we actually want to assert this?
+  end
+
+  it 'extracts the name of the method that was called' do
+    extracts_method_name! '<', "undefined method `<' for nil:NilClass"
+    extracts_method_name! "ab `c' d", "undefined method `ab `c' d' for main:Object"
+  end
+end

data/spec/heuristic/spec_helper.rb

@@ -0,0 +1,33 @@
+require 'spec_helper'
+require 'error_to_communicate/heuristic'
+
+module HeuristicSpecHelpers
+  extend self
+
+  def heuristic_class
+    raise NotImplementedError, 'You need to define the heuristic class!'
+  end
+
+  def heuristic_for(attributes={})
+    heuristic_class.new project: build_default_project(attributes),
+                        einfo:   einfo_for(FakeException.new attributes)
+  end
+
+  def build_default_project(attributes={})
+    ErrorToCommunicate::Project.new \
+      rubygems_dir: attributes.delete(:rubygems_dir),
+      root:         attributes.delete(:root)
+  end
+
+  def is_for!(exception)
+    expect(heuristic_class).to be_for einfo_for(exception)
+  end
+
+  def is_not_for!(exception)
+    expect(heuristic_class).to_not be_for einfo_for(exception)
+  end
+end
+
+RSpec.configure do |config|
+  config.include HeuristicSpecHelpers, heuristic: true
+end

data/spec/heuristic/wrong_number_of_arguments_spec.rb

@@ -0,0 +1,115 @@
+require 'heuristic/spec_helper'
+
+RSpec.describe 'heuristics for the WrongNumberOfArguments', t:true, heuristic: true do
+  def heuristic_class
+    ErrorToCommunicate::Heuristic::WrongNumberOfArguments
+  end
+
+  describe '.for?' do
+    it 'is true when given an MRI style wrong number of arguments message' do
+      is_for! ArgumentError.new "wrong number of arguments (1 for 0)"
+    end
+
+    it 'is true when given an RBX style wrong number of arguments message' do
+      is_for! ArgumentError.new "method 'a': given 1, expected 0"
+    end
+
+    it 'is true when given an JRuby style wrong number of arguments message' do
+      is_for! ArgumentError.new "wrong number of arguments calling `a` (1 for 0)"
+    end
+
+    it 'is true when given an MRI style wrong number of arguments message' do
+      is_for! ArgumentError.new "wrong number of arguments (1 for 0)"
+    end
+
+    it 'is false for ArgumentErrors that are not "wrong number of arguments"' do
+      is_not_for!  ArgumentError.new "Some other kind of ArgumentError"
+    end
+
+    it 'is false when the message is contained within some other message (not overeager)' do
+      is_not_for! RSpec::Expectations::ExpectationNotMetError.new(<<-MESSAGE)
+       expected: "wrong number of arguments (1 for 0) (ArgumentError)"
+            got: "Wrong number of arguments"
+
+            (compared using ==)
+      MESSAGE
+    end
+  end
+
+  describe 'parse' do
+    let(:mri_message) { "wrong number of arguments (1 for 0)" }
+    let(:mri_parsed)  { heuristic_for message: mri_message }
+
+    let(:rbx_message) { "method 'a': given 1, expected 0" }
+    let(:rbx_parsed)  { heuristic_for message: rbx_message }
+
+    let(:jruby_message) { "wrong number of arguments calling `a` (1 for 0)" }
+    let(:jruby_parsed)  { heuristic_for message: "wrong number of arguments calling `a` (1 for 0)" }
+
+    it 'extracts the number of arguments that were passed' do
+      expect(rbx_parsed.num_expected).to eq 0
+      expect(mri_parsed.num_expected).to eq 0
+    end
+
+    it 'extracts the number of arguments that were received' do
+      expect(rbx_parsed.num_received).to eq 1
+      expect(mri_parsed.num_received).to eq 1
+    end
+  end
+
+  let(:message_2_for_3) { "wrong number of arguments calling `a` (1 for 0)" }
+
+  it 'shows the first two lines of the backtrace' do
+    heuristic = heuristic_for message: message_2_for_3, backtrace: [
+      "/a:1:in `a'", "/b:2:in `b'", "/c:3:in `c'"
+    ]
+    _heuristic, codeblocks = heuristic.semantic_info
+    paths = codeblocks.map { |_code, attrs| attrs[:location].path.to_s }
+    expect(paths).to eq ['/a', '/b']
+  end
+
+  it 'only shows one code sample when there is only one line in the backtrace, with context before and after, and no message, and highlights its label on the offchance that this is the right thing to do' do
+    heuristic = heuristic_for message: message_2_for_3, backtrace: ["/a:1:in `b'"]
+    _heuristic, *codeblocks = heuristic.semantic_info
+    expect(codeblocks.length).to eq 1
+    ((_code, attrs)) = codeblocks
+    expect(attrs).to eq highlight: 'b',
+                        context:   (-5..5),
+                        emphasis: :code,
+                        location: ErrorToCommunicate::ExceptionInfo::Location.new(
+                                    path: '/a', linenum: 1, label: 'b'
+                                  )
+  end
+
+  it 'shrugs "sorry" when there are no lines in the backtrace' do
+    heuristic = heuristic_for message: message_2_for_3, backtrace: []
+    expect(heuristic.semantic_info).to eq [:context, "Couldn\'t find anything interesting ¯\_(ツ)_/¯\n"]
+  end
+
+  describe 'When there are at least two lines in the backtrace' do
+    attr_reader :code1, :code2
+    before :each do
+      heuristic = heuristic_for message: message_2_for_3, backtrace: ["/a:1:in `a'", "/b:2:in `b'", "/b:2:in `b'"]
+      heuristic, ((name1, @code1), (name2, @code2), *rest) = heuristic.semantic_info
+      expect(heuristic).to eq :heuristic
+      expect(name1).to eq :code
+      expect(name2).to eq :code
+      expect(rest).to be_empty
+    end
+
+    describe 'the first line' do
+      it 'has a context of 0..5 (b/c it\'s a method definition, so no point in seeing preceding context)'
+      it 'declares the number of expected args as the message'
+      it 'emphasizes the code'
+      it 'highlights it\'s own label (as it is the method name)'
+    end
+
+    describe 'the second line' do
+      it 'has a context of -5..5 so we can see what we were thinking when we called it'
+      it 'declares the number of sent args as the message'
+      it 'emphasizes the code'
+      it 'highlights the first line\'s label (because that\'s the method call)'
+    end
+
+  end
+end

data/spec/heuristic_spec.rb

@@ -0,0 +1,76 @@
+require 'spec_helper'
+require 'error_to_communicate/heuristic'
+require 'heuristic/spec_helper'
+
+RSpec.describe 'Heuristic', heuristic: true do
+  let(:einfo)    { ErrorToCommunicate::ExceptionInfo.new classname: 'the classname', message: 'the message', backtrace: [
+                     ErrorToCommunicate::ExceptionInfo::Location.new(path: 'file', linenum: 12, label: 'a')
+                   ]
+                 }
+  let(:subclass) { Class.new ErrorToCommunicate::Heuristic }
+  let(:instance) { subclass.new einfo: einfo, project: build_default_project }
+
+  it 'expects the subclass to implement .for?' do
+    expect { subclass.for? nil }.to raise_error NotImplementedError, /subclass/
+  end
+
+  it 'records the exception info as einfo' do
+    expect(instance.einfo).to equal einfo
+  end
+
+  it 'delegates classname, and backtrace to einfo' do
+    expect(instance.classname).to eq 'the classname'
+    expect(instance.backtrace.map { |loc| [loc.linenum] }).to eq [[12]]
+  end
+
+  it 'defaults the explanation to einfo\'s message' do
+    expect(instance.explanation).to eq 'the message'
+  end
+
+  describe 'semantic methods' do
+    specify 'semantic_explanation defaults to the explanation' do
+      def instance.explanation; "!#{einfo.message}!"; end
+      expect(instance.semantic_explanation).to eq "!the message!"
+    end
+
+    specify 'semantic_summary includes the classname and semantic_explanation in columns' do
+      def instance.semantic_explanation; 'sem-expl'; end
+      expect(instance.semantic_summary).to eq \
+        [:summary, [
+          [:columns,
+            [:classname,   'the classname'],
+            [:explanation, 'sem-expl']]]]
+    end
+
+    specify 'semantic_info is null by default' do
+      expect(instance.semantic_info).to eq [:null]
+    end
+
+    describe 'semantic_backtrace' do
+      it 'is marked as a backtrace' do
+        expect(instance.semantic_backtrace.first).to eq :backtrace
+      end
+
+      it 'includes code for each line of the backtrace, without context, highlighting the label of the predecessor, and emphasizing the path over the code' do
+        err  = RuntimeError.new('the message')
+        err.set_backtrace ["file1:12:in `a'", "file2:100:in `b'", "file3:94:in `c'"]
+        einfo        = einfo_for err
+        instance     = subclass.new einfo: einfo, project: build_default_project
+        code_samples = instance.semantic_backtrace.last
+        metas        = code_samples.map do |name, metadata, *rest|
+          expect(name).to eq :code
+          expect(rest).to be_empty
+          metadata
+        end
+
+        locations       = metas.map { |m| m[:location] }
+        highlights      = metas.map { |m| m[:highlight] }
+        paths_and_lines = locations.flat_map { |l| [l.path.to_s, l.linenum] }
+        expect(paths_and_lines).to eq ['file1', 12, 'file2', 100, 'file3', 94]
+        expect(highlights).to eq ['b', 'c', nil]
+        expect(metas).to be_all { |m| m[:context] == (0..0) }
+        expect(metas).to be_all { |m| m[:emphasis] == :path }
+      end
+    end
+  end
+end