what_weve_got_here_is_an_error_to_communicate 0.0.1 → 0.0.2

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 6d8b74cd9d659e3218cc9ecad4a0fdbba80b6d07
-  data.tar.gz: eadb2da5ec5d00795c54b93bf8efd7e0304b017d
+  metadata.gz: 502a20709d4fe294ae357bd9652fa9442c14b851
+  data.tar.gz: 8dabffcbda862538f2f3b3791b00b880ed2e9be5
 SHA512:
-  metadata.gz: e060fb388519b4492109c8e31d1f723b6b3cdb939650b6a709348778cbf771f0cbd5f75ec7a866945d140308c58330c5436d464cd01254fea9c4272f4b87c126
-  data.tar.gz: 2df113222792975b9e4bdc07dbdb2190e1f4f67b1ef5b5daa6b13d2fbfaa675755abc92818e873c00e737efdacd84dd38f8790cb49ccac72d72ef23f12fefaa9
+  metadata.gz: f499bc2afd237666020abca95c8938f94a57955906f96340be86c0a67a54e1a09d8862329309eb2c672195360282aff51ab8a22a9555deac9bf923ec1f1ad226
+  data.tar.gz: 2bbd0c0bf81e0ed3fd07aa3eef2552468381e3fccd88b42ca0adc477b2eec10cb3ff6edb2070612b4d826820f655547e204fbb2bf5c8f94a29e20ae455a4eb15

data/.rspec

@@ -1,4 +1,5 @@
 --colour
 --fail-fast
+--require error_to_communicate/at_exit
 --require error_to_communicate/rspec_formatter
 --format WhatWeveGotHereIsAnErrorToCommunicate::RSpecFormatter

data/Readme.md

@@ -3,19 +3,16 @@
 What if error messages were compelling to read?
 -----------------------------------------------
 
-Blog explaining the code is [here](http://blog.turing.io/2015/01/18/what-we-ve-got-here-is-an-error-to-communicate/).
-(or will be once it's merged).
+Blog explaining the goal [here](http://blog.turing.io/2015/01/18/what-we-ve-got-here-is-an-error-to-communicate/).
 
 A screenshot of the code rendering an `ArgumentError`.
 
 ![screenshot](https://s3.amazonaws.com/josh.cheek/images/scratch/better-reuby-commandline-errors.png)
 
-This is a proof of concept
---------------------------
+This is still early and Rough
+-----------------------------
 
-This isn't fit for real-world use.
-If there is resonance in the community, I'll probably try to make it a real gem.
-I'll have some time to do that during my next braeak in late march 2015.
+But I've been using it on its own test suite, and have to say it's compelling!
 
 Inspirations:
 -------------
@@ -25,8 +22,13 @@ Inspirations:
 * Got to thinking about it again with Kerri Miller, conversing at DCamp,
   and then at Ruby Conf, she created [chatty_exceptions](https://github.com/kerrizor/chatty_exceptions)
   which is in this same domain.
+
+Related Projects:
+-----------------
+
 * Charlie Sommerville's [better_errors](https://rubygems.org/gems/better_errors)
   gem gives you a nice interface like this for Rails.
+* Koichi's [pretty_backtrace](https://github.com/ko1/pretty_backtrace)
 
 License
 --------

data/experiments/formatting/other_resources

@@ -0,0 +1,7 @@
+This lib is for working with colours
+  https://github.com/plashchynski/rgb
+
+  if it's well written, could maybe use it to allow you to write css,
+  and then translate the colours to console rgb values (eg the way I
+  printed pictures on the console at
+  https://github.com/JoshCheek/print-png/blob/c73fe7e8e29f44fb420240b4c3d3e134625ede3d/screenshot-rainbow.png)

data/lib/error_to_communicate/at_exit.rb

@@ -1,11 +1,17 @@
 require 'error_to_communicate'
-require 'error_to_communicate/format'
-
-module WhatWeveGotHereIsAnErrorToCommunicate
-  at_exit do
-    exception = $!
-    next unless CONFIG.parse? exception
-    $stderr.puts format CONFIG.parse exception
-    exit! 1 # there has got to be a better way to clear an exception, this could break other at_exit hooks -.^
-  end
+
+# Deal with global deps and console knowledge here
+at_exit do
+  exception = $!
+  config    = ErrorToCommunicate::Config.default
+
+  next unless config.accept? exception
+
+  heuristic = config.heuristic_for exception
+  formatted = config.format heuristic, Dir.pwd
+  $stderr.puts formatted
+
+  # There has got to be a better way to clear an exception,
+  # this could break other at_exit hooks -.^
+  exit! 1
 end

data/lib/error_to_communicate/config.rb

@@ -1,32 +1,65 @@
+require 'pathname'
 require 'error_to_communicate/version'
-require 'error_to_communicate/parse/registry'
-require 'error_to_communicate/parse/exception'
-require 'error_to_communicate/parse/no_method_error'
-require 'error_to_communicate/parse/wrong_number_of_arguments'
+require 'error_to_communicate/theme'
+require 'error_to_communicate/project'
+require 'error_to_communicate/exception_info'
+
+module ErrorToCommunicate
+  autoload :FormatTerminal, 'error_to_communicate/format_terminal'
 
-module WhatWeveGotHereIsAnErrorToCommunicate
   class Config
-    attr_accessor :registry
-
-    def initialize
-      self.registry = Parse::Registry.new(
-        dont_parse: lambda { |exception|
-          exception.kind_of? SystemExit
-        },
-        parsers: [
-          Parse::WrongNumberOfArguments,
-          Parse::NoMethodError,
-          Parse::Exception,
-        ]
-      )
+    # Freezing this to encourage duping it rather than modifying the global default.
+    # This implies we should provide a way to add/remove heuristics on the config itself.
+    require 'error_to_communicate/heuristic/wrong_number_of_arguments'
+    require 'error_to_communicate/heuristic/no_method_error'
+    require 'error_to_communicate/heuristic/load_error'
+    require 'error_to_communicate/heuristic/syntax_error'
+    require 'error_to_communicate/heuristic/exception'
+    DEFAULT_HEURISTICS = [
+      Heuristic::WrongNumberOfArguments,
+      Heuristic::NoMethodError,
+      Heuristic::LoadError,
+      Heuristic::SyntaxError,
+      Heuristic::Exception,
+    ].freeze
+
+    # Should maybe also be an array, b/c there's no great way to add a proc to the blacklist,
+    # right now, it would have to check it's thing and then call the next one
+    DEFAULT_BLACKLIST = lambda do |einfo|
+      einfo.classname == 'SystemExit'
+    end
+
+    def self.default
+      @default ||= new
+    end
+
+    attr_accessor :heuristics, :blacklist, :theme, :format_with, :catchall_heuristic, :project
+
+    def initialize(options={})
+      self.heuristics  = options.fetch(:heuristics)      { DEFAULT_HEURISTICS }
+      self.blacklist   = options.fetch(:blacklist)       { DEFAULT_BLACKLIST }
+      self.theme       = options.fetch(:theme)           { Theme.new } # this is still really fkn rough
+      self.format_with = options.fetch(:format_with)     { FormatTerminal }
+      loaded_features  = options.fetch(:loaded_features) { $LOADED_FEATURES }
+      root             = options.fetch(:root)            { File.expand_path Dir.pwd }
+      self.project     = Project.new root: root, loaded_features: loaded_features
+    end
+
+    def accept?(exception)
+      return false unless ExceptionInfo.parseable? exception
+      einfo = ExceptionInfo.parse(exception)
+      !blacklist.call(einfo) && !!heuristics.find { |h| h.for? einfo }
     end
 
-    def parse?(exception)
-      registry.parse?(exception)
+    def heuristic_for(exception)
+      accept?(exception) || raise(ArgumentError, "Asked for a heuristic on an object we don't accept: #{exception.inspect}")
+      einfo = ExceptionInfo.parse(exception)
+      heuristics.find { |heuristic| heuristic.for? einfo }
+                .new(einfo: einfo, project: project)
     end
 
-    def parse(exception)
-      registry.parse(exception)
+    def format(heuristic, cwd)
+      format_with.call theme: theme, heuristic: heuristic, cwd: Pathname.new(cwd)
     end
   end
 end

data/lib/error_to_communicate/exception_info.rb

@@ -1,41 +1,96 @@
-module WhatWeveGotHereIsAnErrorToCommunicate
+require 'pathname'
+
+module ErrorToCommunicate
   class ExceptionInfo
-    attr_accessor :classname, :explanation, :backtrace
-    attr_accessor :exception # for dev info only, parse out additional info rather than interacting with it direclty
-    def initialize(attributes)
-      self.exception   = attributes.fetch :exception, nil
-      self.classname   = attributes.fetch :classname
-      self.explanation = attributes.fetch :explanation
-      self.backtrace   = attributes.fetch :backtrace
-    end
   end
+end
 
-  class ExceptionInfo::Location
-    # TODO: rename linenum -> line_number
-    attr_accessor :path, :linenum, :label, :pred, :succ
-    def initialize(attributes)
-      self.path    = attributes.fetch :path
-      self.linenum = attributes.fetch :linenum
-      self.label   = attributes.fetch :label
-      self.pred    = attributes.fetch :pred, nil
-      self.succ    = attributes.fetch :succ, nil
-    end
+class ErrorToCommunicate::ExceptionInfo::Location
+  attr_accessor :path, :linenum, :label, :pred, :succ
+
+  def initialize(attributes)
+    self.path    = Pathname.new attributes.fetch(:path)
+    self.linenum = attributes.fetch :linenum
+    self.label   = attributes.fetch :label
+    self.pred    = attributes.fetch :pred, nil
+    self.succ    = attributes.fetch :succ, nil
   end
 
-  class ExceptionInfo::WrongNumberOfArguments < ExceptionInfo
-    attr_accessor :num_expected, :num_received
-    def initialize(attributes)
-      self.num_expected = attributes.fetch :num_expected
-      self.num_received = attributes.fetch :num_received
-      super
-    end
+  # What if the line doesn't match for some reason?
+  # Raise an exception?
+  # Use some reasonable default? (is there one?)
+  def self.parse(line)
+    line =~ /^(.*?):(\d+):in `(.*?)'$/ # Are ^ and $ sufficient? Should be \A and (\Z or \z)?
+    ErrorToCommunicate::ExceptionInfo::Location.new(
+      path:    $1,
+      linenum: $2.to_i,
+      label:   $3,
+    )
   end
 
-  class ExceptionInfo::NoMethodError < ExceptionInfo
-    attr_accessor :undefined_method_name
-    def initialize(attributes)
-      self.undefined_method_name = attributes.fetch :undefined_method_name
-      super
+  # is there an upper bound I need to stay within? Guessing 30 or 31 bits,
+  # but maybe it doesn't really matter?
+  def hash
+    path.hash + linenum.hash + label.hash
+  end
+
+  def ==(location)
+    path    == location.path    &&
+    linenum == location.linenum &&
+    label   == location.label
+  end
+
+  alias eql? ==
+
+  def inspect
+    "#<ExInfo::Loc #{path}:#{linenum}:in `#{label}' pred:#{!!pred} succ:#{!!succ}>"
+  end
+end
+
+# Wraps an exception in our internal data structures
+# So we can normalize the different things that come in,
+# and you can use code that needs this info without
+# going to the effort of raising exceptions
+class ErrorToCommunicate::ExceptionInfo
+  attr_accessor :classname
+  attr_accessor :message
+  attr_accessor :backtrace
+
+  def initialize(attributes)
+    self.exception = attributes.fetch :exception, nil
+    self.classname = attributes.fetch :classname
+    self.message   = attributes.fetch :message
+    self.backtrace = attributes.fetch :backtrace
+  end
+
+  attr_writer :exception
+  private     :exception=
+  def exception
+    @warned_about_exception ||= begin
+      warn "The exception is recorded for debugging purposes only.\n"
+      warn "Don't write code that depends on it, or we can't generically use the ExceptionInfo structure."
+      true
     end
+    @exception
+  end
+
+  def self.parseable?(exception)
+    exception.respond_to?(:message) && exception.respond_to?(:backtrace)
+  end
+
+  def self.parse(exception)
+    return exception if exception.kind_of? self
+    new exception: exception,
+        classname: exception.class.name,
+        message:   exception.message,
+        backtrace: parse_backtrace(exception)
+  end
+
+  def self.parse_backtrace(exception)
+    # Really, there are better methods, e.g. backtrace_locations,
+    # but they're unevenly implemented across versions and implementations
+    (exception.backtrace||[])
+      .map { |line| Location.parse line }
+      .tap { |locs| locs.each_cons(2) { |crnt, pred| crnt.pred, pred.succ = pred, crnt } }
   end
 end

data/lib/error_to_communicate/format_terminal.rb

@@ -0,0 +1,146 @@
+require 'rouge'
+
+module ErrorToCommunicate
+  class FormatTerminal
+    def self.call(attributes)
+      new(attributes).call
+    end
+
+    attr_accessor :cwd, :theme, :heuristic, :format_code, :heuristic_formatter
+    def initialize(attributes)
+      self.cwd         = attributes.fetch :cwd
+      self.theme       = attributes.fetch :theme
+      self.heuristic   = attributes.fetch :heuristic
+      self.format_code = FormatTerminal::Code.new theme: theme, cwd: cwd # defined below
+    end
+
+    # Really, it seems like #format should be #call,
+    # which implies that there are two objects in here.
+    # One that does the semantic formatting, and one that translates that to text.
+    # But I can't quite see it yet, so going to wait until there are more requirements on this.
+    def call
+      format [
+        heuristic.semantic_summary,
+        heuristic.semantic_info,
+        heuristic.semantic_backtrace,
+      ]
+    end
+
+    # TODO: not good enough,
+    # These need to be able to take things like:
+    # [:message, ["a", [:explanation, "b"], "c"]]
+    # where "a", and "c", get coloured with the semantics of :message
+    def format(semantic_content)
+      return semantic_content unless semantic_content.kind_of? Array
+
+      meaning, content, *rest = semantic_content
+      case meaning
+      when Array        then semantic_content.map { |c| format c }.join
+      when :summary     then format([:separator]) + format(content)
+      when :heuristic   then format([:separator]) + format(content)
+      when :backtrace   then format([:separator]) + format(content)
+      when :separator   then theme.separator_line
+      when :columns     then theme.columns     [content, *rest].map { |c| format c }
+      when :classname   then theme.classname   format content
+      when :message     then theme.message     format content
+      when :explanation then theme.explanation format content
+      when :context     then theme.context     format content
+      when :details     then theme.details     format content
+      when :code        then format_code.call  content
+      when :null        then ''
+      else raise "Wat is #{meaning.inspect}?"
+      end
+    end
+
+
+    class Code
+      # TODO: Should this highlight the location?
+
+      attr_accessor :theme, :cwd
+
+      def initialize(attributes)
+        self.theme = attributes.fetch :theme
+        self.cwd   = attributes.fetch :cwd
+      end
+
+      def call(attributes)
+        location       = attributes.fetch :location
+        path           = location.path
+        line_index     = location.linenum - 1
+        highlight      = attributes.fetch :highlight, location.label
+        end_index      = bound_num min: 0, num: line_index+attributes.fetch(:context).end
+        start_index    = bound_num min: 0, num: line_index+attributes.fetch(:context).begin
+        message        = attributes.fetch :message, ''
+        message_offset = line_index - start_index
+
+        # first line gives the path
+        path_line = [
+          theme.color_path("#{path_to_dir cwd, path}/"),
+          theme.color_filename(path.basename),
+          ":",
+          theme.color_linenum(location.linenum),
+        ].join("")
+
+        # then display the code
+        if path.exist?
+          code = File.read(path).lines[start_index..end_index].join("")
+          code = remove_indentation       code
+          code = theme.syntax_highlight   code
+          code = prefix_linenos_to        code, start_index.next, mark: location.linenum
+          code = theme.indent             code, "  "
+          code = add_message_to           code, message_offset, theme.screaming_red(message)
+          code = theme.highlight_text           code, message_offset, highlight
+        else
+          code = "Can't find code\n"
+        end
+
+        # adjust for emphasization
+        if attributes.fetch(:emphasis) == :path
+          path_line = theme.underline      path_line
+          code      = theme.indent         code, "      "
+          code      = theme.desaturate     code
+          code      = theme.highlight_text code, message_offset, highlight # b/c desaturate really strips color
+        end
+
+        # all together
+        path_line << "\n" << code
+      end
+
+      def path_to_dir(from, to)
+        to.expand_path.relative_path_from(from).dirname
+      rescue ArgumentError
+        return to # eg rbx's core code
+      end
+
+      def bound_num(attributes)
+        num = attributes.fetch :num
+        min = attributes.fetch :min
+        num < min ? min : num
+      end
+
+      def remove_indentation(code)
+        indentation = code.scan(/^\s*/).min_by(&:length)
+        code.gsub(/^#{indentation}/, "")
+      end
+
+      def prefix_linenos_to(code, start_linenum, options)
+        line_to_mark  = options.fetch :mark, -1
+        lines         = code.lines
+        max_linenum   = lines.count + start_linenum - 1 # 1 to translate to indexes
+        linenum_width = max_linenum.to_s.length + 1     # 1 for the colon
+        lines.zip(start_linenum..max_linenum)
+             .map { |line, num|
+               formatted_num = "#{num}:".ljust(linenum_width)
+               formatted_num = theme.mark_linenum formatted_num if line_to_mark == num
+               theme.color_linenum(formatted_num) << " " << line
+             }.join("")
+      end
+
+      def add_message_to(code, offset, message)
+        lines = code.lines
+        lines[offset].chomp! << " " << message << "\n"
+        lines.join("")
+      end
+    end
+  end
+end

data/lib/error_to_communicate/heuristic/exception.rb

@@ -0,0 +1,22 @@
+require 'error_to_communicate/heuristic'
+
+module ErrorToCommunicate
+  class Heuristic
+    class Exception < Heuristic
+      def self.for?(einfo)
+        true
+      end
+
+      def semantic_info
+        [:heuristic,
+          [:code, {
+            location:  backtrace[0],
+            highlight: backtrace[0].label,
+            context:   -5..5,
+            emphasis:  :code,
+          }]
+        ]
+      end
+    end
+  end
+end

data/lib/error_to_communicate/heuristic/load_error.rb

@@ -0,0 +1,57 @@
+require 'pathname'
+require 'error_to_communicate/heuristic'
+
+module ErrorToCommunicate
+  class Heuristic
+    class LoadError < Heuristic
+      def self.for?(einfo)
+        einfo.classname == 'LoadError' &&
+          einfo.message.include?(' -- ')
+      end
+
+      def path
+        @path ||= Pathname.new einfo.message.split(' -- ', 2).last
+      end
+
+      def semantic_info
+        heuristic = if relevant_locations.any?
+          relevant_locations.map { |location|
+            [:code, {
+              location:  location,
+              highlight: location.label,
+              context:   -5..5,
+              message:   "Couldn't find #{path.to_s.inspect}",
+              emphasis:  :code,
+            }]
+          }
+        else
+          # The newline here implies the semantic analysis needs to get better,
+          # it only does this b/c it should be a block-element, but isn't being sectioned like that, correctly
+          [:context, "Couldn\'t find anything interesting ¯\_(ツ)_/¯\n"]
+        end
+
+        [:heuristic, heuristic]
+      end
+
+      def relevant_locations
+        @relevant_locations ||= [first_nongem_line, first_line_within_lib].compact.uniq
+      end
+
+      def first_nongem_line
+        relevant_backtrace.first
+      end
+
+      def first_line_within_lib
+        @first_line_within_lib ||= relevant_backtrace.find { |loc| loc.path.to_s.start_with? project.root }
+      end
+
+      private
+
+      def relevant_backtrace
+        @relevant_backtrace ||= relevant_backtrace = project.rubygems? ?
+          backtrace :
+          backtrace.drop_while { |loc| loc.path.to_s.start_with? project.rubygems_dir }
+      end
+    end
+  end
+end

data/lib/error_to_communicate/heuristic/no_method_error.rb

@@ -0,0 +1,35 @@
+require 'error_to_communicate/heuristic'
+
+module ErrorToCommunicate
+  class Heuristic
+    class NoMethodError < Heuristic
+      def self.for?(einfo)
+        ( einfo.classname == 'NoMethodError' ||
+          einfo.classname == 'NameError'
+        ) && parse_undefined_name(einfo)
+      end
+
+      def undefined_method_name
+        self.class.parse_undefined_name einfo
+      end
+
+      def semantic_info
+        [:heuristic,
+          [:code, {
+            location:  backtrace[0],
+            highlight: backtrace[0].label,
+            context:   -5..5,
+            message:   "#{undefined_method_name} is undefined",
+            emphasis:  :code,
+          }]
+        ]
+      end
+
+      private
+
+      def self.parse_undefined_name(einfo)
+        einfo.message[/`(.*)'/, 1]
+      end
+    end
+  end
+end

data/lib/error_to_communicate/heuristic/syntax_error.rb

@@ -0,0 +1,55 @@
+require 'error_to_communicate/heuristic'
+
+module ErrorToCommunicate
+  class Heuristic
+    class SyntaxError < Heuristic
+      def self.for?(einfo)
+        einfo.classname == 'SyntaxError' && parse_message(einfo.message)
+      end
+
+
+      attr_accessor :reported_file, :reported_line, :unexpected, :expected, :invalid_loc
+
+      def initialize(*)
+        super
+        self.reported_file ,
+        self.reported_line ,
+        self.unexpected    ,
+        self.expected      = self.class.parse_message(einfo.message)
+        self.invalid_loc   = ExceptionInfo::Location.new \
+                               path:    reported_file,
+                               linenum: reported_line,
+                               label:   "unexpected #{unexpected}, expected: #{expected}",
+                               pred:    backtrace[0]
+      end
+
+      def semantic_info
+        [:heuristic,
+          [:code, {
+            location:  invalid_loc,
+            context:   -5..5,
+            message:   "unexpected #{unexpected}, expected #{expected}",
+            emphasis:  :code,
+          }]
+        ]
+      end
+
+      def semantic_explanation
+        [ :message,
+          [ [:context, 'Unexpected '],
+            [:details, unexpected],
+            [:context, ', expected'],
+            [:details, expected],
+          ]
+        ]
+      end
+
+      # "/Users/josh/code/what-we-ve-got-here-is-an-error-to-communicate/proving_grounds/simple_syntax_error.rb:2: syntax error, unexpected end-of-input, expecting keyword_end"
+      def self.parse_message(message)
+        return if message !~ /^(.*?):(\d+):.*?unexpected (.*?), expecting (.*)$/
+        file, line, unexpected, expected = $1, $2.to_i, $3, $4
+        [file, line, unexpected, expected]
+      end
+    end
+  end
+end