enhanced_errors 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1381112bfa16b295aa6916a6248fba5951ae7362984fd7741d8cef0c81d60769
+  data.tar.gz: e60c4a237637dae49192c670ed291d1b6d90d97ea868572b834df2ec17c0e048
+SHA512:
+  metadata.gz: 387e0660918b06a32515f2ef928d9caacf4394640bce877438b4d25d278664999d831aef693bb128b24efbed490e66991b32a1663927b099fa50fb1d77d1e620
+  data.tar.gz: fbfdee8971f463d7697321b4873fd0bc4a48ca39acd59f172ca81e64b8e52bde4c5a83d3c56599e772bfdc61eae034b179fbd7bec42dee1442685fd23e00919d

data/LICENSE

@@ -0,0 +1,19 @@
+Copyright (c) 2019-2024 Eric Beland
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

data/README.md

@@ -0,0 +1,367 @@
+# EnhancedErrors
+
+## Overview
+
+**EnhancedErrors** is a pure Ruby gem that enhances exception messages by capturing and appending variables and their values from the scope where the error was raised.
+
+**EnhancedErrors** leverages Ruby's built-in [TracePoint](https://ruby-doc.org/core-3.1.0/TracePoint.html) feature to provide detailed context for exceptions, making debugging easier without significant performance overhead.
+
+When an exception is raised, EnhancedErrors captures the surrounding context.  It works like this:
+
+```ruby
+
+require './lib/enhanced_errors'
+require 'awesome_print' # Optional, for better output
+
+EnhancedErrors.enhance!
+
+def foo
+  begin
+    myvar = 0
+    @myinstance = 10
+    foo = @myinstance / myvar
+  rescue => e
+    puts e.message
+  end
+end
+
+foo
+
+```
+
+#### Enhanced Exception In Code:
+
+<img src="./doc/images/enhanced-error.png" style="height: 171px; width: 440px;"></img>
+
+
+```ruby
+  describe 'attains enlightenment' do
+    let(:the_matrix) { 'code rains, dramatically' }
+
+    before(:each) do
+      @spoon = 'there is no spoon'
+    end
+
+    it 'in the matrix' do
+      #activate memoized item
+      the_matrix
+      stop = 'bullets'
+      raise 'No!'
+    end
+  end
+```
+
+#### Enhanced Exception In Specs:
+
+<img src="./doc/images/enhanced-spec.png" style="height: 426px; width: 712px;"></img>
+
+
+## Features
+
+- **Pure Ruby**: No external dependencies or C extensions.
+- **Standalone**: Does not rely on any external libraries.
+- **Lightweight**: Minimal performance impact, as tracing is only active during exception raising.
+- **Customizable Output**: Supports multiple output formats (`:json`, `:plaintext`, `:terminal`).
+- **Flexible Hooks**: Redact or modifying captured data via the `on_capture` hook.
+- **Environment-Based Defaults**: For Rails apps, automatically adjusts settings based on the environment (`development`, `test`, `production`, `ci`).
+- **Pre-Populated Skip List**: Comes with predefined skip lists to exclude irrelevant variables from being captured.
+- **Capture Levels**: Supports `info` and `debug` levels, where `debug` level ignores the skip lists for more comprehensive data capture.
+- **Capture Types**: Captures variables from the first `raise` and the last `rescue` for an exception by default.
+- **No dependencies**:  EnhancedErrors does not ___require___ any dependencies--it uses [awesome_print](https://github.com/awesome-print/awesome_print) for nicer output if it is installed and available.
+
+EnhancedErrors has a few big use-cases:
+
+* Data-driven bugs. For example, if, while processing a 10 gig file, you get an error, you can't just re-run the code with a debugger.
+You also can't just print out all the data, because it's too big. You want to know what the data was the cause of the error.
+Ideally, without long instrument-re-run-fix loops. 
+
+If your logging didn't capture the data, normally, you'd be stuck. 
+
+* Debug a complex application erroring deep in the stack when you can't tell where the error originates
+
+* Faster TDD - Often, you won't have to re-run to see an error--you can go straight to the fix.
+
+* Faster CI -> Dev fixes. When a bug happens in CI, usually there's a step where you first reproduce it locally.
+  EnhancedErrors can help you skip that step.
+
+* Faster debugging. In general, you can skip the add-instrumentation step and jump to the fix.
+
+* Heisenbugs - bugs that disappear when you try to debug them. EnhancedErrors can help you capture the data that causes the bug before it disappears.
+
+* "Unknown Unknowns" - you can't pre-emptively log variables from failure cases you never imagined.
+
+* Cron jobs and daemons - when it fails for unknown reasons at 4am, check the log and fix--it probably has what you need.
+
+## Installation
+
+Add this line to your `Gemfile`:
+
+```ruby
+gem 'enhanced_errors'
+```
+
+Then execute:
+
+```shell
+$ bundle install
+```
+
+Or install it yourself with:
+
+```shell
+$ gem install enhanced_errors
+```
+
+## Basic Usage
+
+To enable EnhancedErrors, call the `enhance!` method:
+
+```ruby
+EnhancedErrors.enhance!
+```
+
+This activates the TracePoint to start capturing exceptions and their surrounding context.
+
+### Configuration Options
+
+You can pass configuration options to `enhance!`:
+
+```ruby
+EnhancedErrors.enhance!(enabled: true, max_length: 2000) do
+  # Additional configuration here
+  add_to_skip_list :@instance_variable_to_skip, :local_to_skip
+end
+
+```
+- `enabled`: Enables or disables the enhancement (default: `true`).
+- `max_length`: Sets the maximum length of the enhanced message (default: `2500`).
+
+### Environment-Based Defaults
+
+EnhancedErrors adjusts its default settings based on the environment:
+
+- **Development/Test**:
+    - Default Output format: `:terminal`
+    - Terminal Color output: Enabled
+- **Production**:
+    - Output format: `:json`
+    - Terminal Color output: Disabled
+- **CI Environment**:
+    - Output format: `:plaintext`
+    - Color output: Disabled
+
+The environment is determined by `ENV['RAILS_ENV']`, `ENV['RACK_ENV']`, or detected CI environment variables like:
+- `CI=true`
+
+### Output Formats
+
+You can customize the output format:
+
+- **`:json`**: Outputs the captured data in JSON format.
+- **`:plaintext`**: Outputs plain text without color codes.
+- **`:terminal`**: Outputs text with terminal color codes.
+
+Example:
+
+```ruby
+EnhancedErrors.format(captured_bindings, :json)
+```
+
+### Customizing Data Capture
+
+#### Using `on_capture`
+
+The `on_capture` hook allows you to modify or redact data as it is captured. For each captured binding
+it yields out a hash with the structure below. Modify it as needed and return the modified hash.
+
+```ruby 
+{
+  source: source_location,
+  object: Object source of error,
+  library: true or false,
+  method_and_args: method_and_args,
+  variables: {
+    locals: locals,
+    instances: instances,
+    lets: lets,
+    globals: globals
+  },
+  exception: exception.class.name,
+  capture_type: capture_type # 'raise' or 'rescue'
+}
+```
+
+
+```ruby
+EnhancedErrors.on_capture do |binding_info|
+  # Redact sensitive data
+  if binding_info[:variables][:locals][:password]
+    binding_info[:variables][:locals][:password] = '[REDACTED]'
+  end
+  binding_info  # Return the modified binding_info
+end
+```
+
+
+#### Using `eligible_for_capture`
+
+The `eligible_for_capture` hook yields an Exception, and allows you to decide whether you want to capture it or not.
+By default, all exceptions are captured. When the block result is true, the error will be captured.
+Error capture is relatively cheap, but ignoring errors you don't care about makes it almost totally free.
+One use-case for eligible_for_capture is to run a string or regexp off a setting flag, which 
+lets you turn on and off what you capture without redeploying.
+
+```ruby 
+EnhancedErrors.eligible_for_capture do |exception|
+  exception.class.name == 'ExceptionIWantTOCatch'
+end
+
+
+```
+
+#### Using `on_format`
+
+`on_format` is the last stop for the message string that will be appended to `exception.message`.
+
+Here it can be encrypted, rewritten, or otherwise modified.
+
+
+```ruby
+EnhancedErrors.on_format do |formatted_string|
+  "---whatever--- #{formatted_string} ---whatever---"
+end
+
+```
+
+
+#### Applying a Variable Skip List
+
+EnhancedErrors comes with predefined skip lists to exclude sensitive or irrelevant variables. 
+By default, the skip list is used to remove a lot of framework noise from Rails and RSpec.
+You can add additional variables to the skip list as needed:
+
+```ruby
+ 
+EnhancedErrors.enhance! do
+  add_to_skip_list :@variable_to_skip
+end
+
+```
+
+The skip list is pre-populated with common variables to exclude and can be extended based on your application's requirements. 
+
+
+
+
+### Capture Levels
+
+EnhancedErrors supports different capture levels to control the verbosity of the captured data:
+
+- **Info Level**: Respects the skip list, excluding predefined sensitive or irrelevant variables. Global variables are ignored.
+- **Debug Level**: Ignores the skip lists, capturing all variables including those typically excluded and global variables.
+  Global variables,
+
+**Default Behavior**: By default, `info` level is used, which excludes variables in the skip list to protect sensitive information. In `debug` mode, the skip lists are ignored to provide more comprehensive data, which is useful during development but should be used cautiously to avoid exposing sensitive data.
+The info mode is recommended.
+
+
+
+### Capture Types
+
+EnhancedErrors differentiates between two types of capture events:
+
+- **`raise`**: Captures the context when an exception is initially raised.
+- **`rescue`**: Captures the context when an exception is last rescued.
+
+**Default Behavior**: By default, EnhancedErrors returns the first `raise` and the last `rescue` event for each exception. 
+This provides a clear picture of where and how the exception was handled.
+
+
+### Example: Redacting Sensitive Information
+
+```ruby
+EnhancedErrors.on_capture do |binding_info|
+  sensitive_keys = [:password, :ssn, :health_info]
+  sensitive_keys.each do |key|
+    if binding_info[:variables][:locals][key]
+      binding_info[:variables][:locals][key] = '[REDACTED]'
+    end
+  end
+  binding_info
+end
+```
+
+### Example: Encrypting Data in Custom Format
+
+
+```ruby
+# config/initializers/encryption.rb
+
+require 'active_support'
+
+# Retrieve the encryption key from Rails credentials or environment variables
+ENCRYPTION_KEY = Rails.application.credentials.encryption_key || ENV['ENCRYPTION_KEY']
+
+# It's recommended to use a 256-bit key (32 bytes)
+# If your key is in hex or another format, ensure it's properly decoded
+key = ActiveSupport::KeyGenerator.new(ENCRYPTION_KEY).generate_key('enhanced_errors', 32)
+ENCRYPTOR = ActiveSupport::MessageEncryptor.new(key)
+```
+
+```ruby
+
+require_relative 'path_to/enhanced_errors' # Adjust the path accordingly
+require 'active_support/message_encryptor'
+
+# Ensure the encryptor is initialized
+encryptor = ENCRYPTOR
+
+EnhancedErrors.on_format = lambda do |formatted_string|
+  encrypted_data = encryptor.encrypt_and_sign(formatted_string)
+  encrypted_base64 = Base64.strict_encode64(encrypted_data)
+  "ENCRYPTED[#{encrypted_data}]"
+end
+```
+
+
+## How It Works
+
+EnhancedErrors uses Ruby's `TracePoint` to listen for `:raise` and `:rescue` events. 
+When an exception is raised or rescued, it captures:
+
+- **Local Variables**: Variables local to the scope where the exception occurred.
+- **Instance Variables**: Instance variables of the object.
+- **Method and Arguments**: The method name and its arguments.
+- **Let Variables**: RSpec let variables, if applicable. Only memoized (evaluated) let variables are captured.
+- **Global Variables**: Global variables, in debug mode.
+
+The captured data includes a `capture_type` field indicating whether the data was captured during a `raise` or `rescue` event. By default, EnhancedErrors returns the first `raise` and the last `rescue` event for each exception, providing a clear trace of the exception lifecycle.
+
+The captured data is then appended to the exception's message, providing rich context for debugging.
+
+
+## Awesome Print
+
+EnhancedErrors uses the [awesome_print](https://github.com/awesome-print/awesome_print) 
+gem to format the captured data, if it is installed and available.
+If not, errors should still work, but the output may be less readable.  AwesomePrint is not
+required directly by EnhancedErrors, so you will need to add it to your Gemfile if you want to use it.
+
+```ruby
+gem 'awesome_print'
+```
+
+
+## Performance Considerations
+
+- **Minimal Overhead**: Since TracePoint is only activated during exception raising and rescuing, the performance impact is negligible during normal operation.
+- **Production Safe**: The gem is designed to be safe for production use, giving you valuable insights without compromising performance.
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at [https://github.com/your_username/enhanced_errors](https://github.com/your_username/enhanced_errors).
+
+## License
+
+The gem is available as open-source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+

data/benchmark/benchmark.rb

@@ -0,0 +1,88 @@
+require 'benchmark'
+require_relative '../lib/enhanced_errors' # Adjust the path if necessary
+
+# Define the number of iterations
+ITERATIONS = 10_000
+EXCEPTIONS_PER_BATCH = 100
+
+class Boo < StandardError; end
+
+def calculate_cost(time_in_seconds)
+  milliseconds = time_in_seconds * 1000
+  (milliseconds / (ITERATIONS / EXCEPTIONS_PER_BATCH)).round(2)
+end
+
+def with_enhanced_errors
+  EnhancedErrors.enhance!(debug: false)
+  ITERATIONS.times do
+    begin
+      foo = 'bar'
+      @boo = 'baz'
+      raise 'Test exception with EnhancedErrors'
+    rescue => e
+      e.message
+    end
+  end
+end
+
+def without_enhanced_errors
+  ITERATIONS.times do
+    begin
+      foo = 'bar'
+      @boo = 'baz'
+      raise 'Test exception without EnhancedErrors'
+    rescue => e
+      e.message
+    end
+  end
+end
+
+def when_capture_only_regexp_matched
+  EnhancedErrors.enhance!(debug: false) do
+    eligible_for_capture { |exception| !!/Boo/.match(exception.class.to_s) }
+  end
+
+  ITERATIONS.times do
+    begin
+      foo = 'bar'
+      @boo = 'baz'
+      raise Boo.new('Test exception with EnhancedErrors')
+    rescue => e
+      e.message
+    end
+  end
+end
+
+def when_capture_only_regexp_did_not_match
+  EnhancedErrors.enhance!(debug: false) do
+    eligible_for_capture { |exception| !!/Baz/.match(exception.class.to_s) }
+  end
+
+  ITERATIONS.times do
+    begin
+      foo = 'bar'
+      @boo = 'baz'
+      raise Boo.new('Test exception with EnhancedErrors')
+    rescue => e
+      e.message
+    end
+  end
+end
+
+puts "Cost Exploration\n"
+Benchmark.bm(35) do |x|
+  without_time = x.report('10k Without EnhancedErrors:') { without_enhanced_errors }
+  with_time = x.report('10k With EnhancedErrors:') { with_enhanced_errors }
+
+  puts "\nCost per 100 exceptions (Without EnhancedErrors): #{calculate_cost(without_time.real)} ms"
+  puts "Cost per 100 exceptions (With EnhancedErrors): #{calculate_cost(with_time.real)} ms"
+end
+
+puts "\nProof that if you only match the classes you care about, the cost is nominal\n"
+Benchmark.bm(35) do |x|
+  matched_time = x.report('10k With capture_only_regexp match:') { when_capture_only_regexp_matched }
+  not_matched_time = x.report('10k Without capture_only_regexp match:') { when_capture_only_regexp_did_not_match }
+
+  puts "\nCost per 100 exceptions (Capture Only Match): #{calculate_cost(matched_time.real)} ms"
+  puts "Cost per 100 exceptions (No Match): #{calculate_cost(not_matched_time.real)} ms"
+end

data/benchmark/stackprofile.rb

@@ -0,0 +1,31 @@
+require 'stackprof'
+require_relative '../lib/enhanced_errors' # Adjust the path if necessary
+
+# gem install stackprof
+
+# adjust path as needed
+# ruby ./lib/core_ext/enhanced_errors/benchmark/stackprofile.rb
+# dumps to current folder. read the stackprof dump:
+# stackprof stackprof.dump
+
+# Define the number of iterations
+ITERATIONS = 10_000
+
+def run_with_enhanced_errors
+  EnhancedErrors.enhance!(debug: false)
+  ITERATIONS.times do
+    begin
+      raise 'Test exception with EnhancedErrors'
+    rescue => _e
+      # Exception handled with EnhancedErrors.
+    end
+  end
+end
+
+def stackprofile
+  StackProf.run(mode: :wall, out: 'stackprof.dump') do
+    run_with_enhanced_errors
+  end
+end
+
+stackprofile

data/enhanced_errors.gemspec

@@ -0,0 +1,24 @@
+Gem::Specification.new do |spec|
+  spec.name = "enhanced_errors"
+  spec.version = "0.1.0"
+  spec.authors = ["Eric Beland"]
+
+  spec.summary = "Automatically enhance your errors with messages containing variable values from the moment they were raised."
+  spec.description = "With no extra dependencies, and using only Ruby's built-in TracePoint, EnhancedErrors will automatically enhance your errors with messages containing variable values from the moment they were raised."
+  spec.homepage = "https://github.com/ericbeland/enhanced_errors."
+  spec.required_ruby_version = ">= 3.0.0"
+
+  spec.metadata["homepage_uri"] = spec.homepage
+  spec.metadata["source_code_uri"] = "https://github.com/ericbeland/enhanced_errors"
+
+  # Specify which files should be added to the gem when it is released.
+  # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .circleci appveyor Gemfile])
+    end
+  end
+  spec.require_paths = ["lib"]
+  spec.add_development_dependency "rspec", "> 3.4.0"
+end

data/examples/division_by_zero_example.rb

@@ -0,0 +1,16 @@
+require './lib/enhanced_errors'
+require 'awesome_print' # Optional, for better output
+
+EnhancedErrors.enhance!
+
+def foo
+  begin
+    myvar = 0
+    @myinstance = 10
+    foo = @myinstance / myvar
+  rescue => e
+    puts e.message
+  end
+end
+
+foo

data/examples/example_spec.rb

@@ -0,0 +1,27 @@
+require 'rspec'
+require_relative '../lib/enhanced_errors'
+
+# INSTRUCTIONS:  Install rspec
+# gem install rspec
+# rspec examples/example_spec.rb
+
+RSpec.describe 'Neo' do
+  before(:each) do
+    EnhancedErrors.enhance!
+  end
+
+  describe 'attains enlightenment' do
+    let(:the_matrix) { 'code rains, dramatically' }
+
+    before(:each) do
+      @spoon = 'there is no spoon'
+    end
+
+    it 'in the matrix' do
+      #activate memoized item
+      the_matrix
+      stop = 'bullets'
+      raise 'No!'
+    end
+  end
+end

data/lib/binding.rb

@@ -0,0 +1,11 @@
+module Debugging
+  def let_vars_hash
+    memoized_values = self.receiver.instance_variable_get(:@__memoized)&.instance_variable_get(:@memoized)
+    memoized_values && !memoized_values.empty? ? memoized_values.dup : {}
+  end
+end
+
+class Binding
+  include Debugging
+end
+

data/lib/colors.rb

@@ -0,0 +1,27 @@
+class Colors
+  COLORS = { red: 31, green: 32, yellow: 33, blue: 34, purple: 35, cyan: 36, white: 0 }
+
+  class << self
+    def enabled?
+      @enabled
+    end
+
+    def enabled=(value)
+      @enabled = value
+    end
+
+    def color(num, string)
+      @enabled ? "#{code(num)}#{string}#{code(0)}" : string
+    end
+
+    def code(num)
+      "\e[#{num}m"
+    end
+
+    COLORS.each do |color, code|
+      define_method(color) do |str|
+        color(COLORS[color], str)
+      end
+    end
+  end
+end

data/lib/enhanced_errors.rb

@@ -0,0 +1,583 @@
+require 'set'
+require 'json'
+
+require_relative 'colors'
+require_relative 'error_enhancements'
+require_relative 'binding'
+
+# The EnhancedErrors class provides mechanisms to enhance exception handling by capturing
+# additional context such as binding information, variables, and method arguments when exceptions are raised.
+# It offers customization options for formatting and filtering captured data.
+class EnhancedErrors
+  class << self
+    # @!attribute [rw] enabled
+    #   @return [Boolean] Indicates whether EnhancedErrors is enabled.
+    attr_accessor :enabled
+
+    # @!attribute [rw] trace
+    #   @return [TracePoint, nil] The TracePoint object used for tracing exceptions.
+    attr_accessor :trace
+
+    # @!attribute [rw] config_block
+    #   @return [Proc, nil] The configuration block provided during enhancement.
+    attr_accessor :config_block
+
+    # @!attribute [rw] max_length
+    #   @return [Integer] The maximum length of the formatted exception message.
+    attr_accessor :max_length
+
+    # @!attribute [rw] on_capture_hook
+    #   @return [Proc, nil] Hook to modify binding information upon capture.
+    attr_accessor :on_capture_hook
+
+    # @!attribute [rw] capture_let_variables
+    #   @return [Boolean] Determines whether RSpec `let` variables are captured.
+    attr_accessor :capture_let_variables
+
+    # @!attribute [rw] eligible_for_capture
+    #   @return [Proc, nil] A proc that determines if an exception is eligible for capture.
+    attr_accessor :eligible_for_capture
+
+    # @!attribute [rw] skip_list
+    #   @return [Set<Symbol>] A set of variable names to exclude from binding information.
+    attr_accessor :skip_list
+
+    # @!constant GEMS_REGEX
+    #   @return [Regexp] Regular expression to identify gem paths.
+    GEMS_REGEX = %r{[\/\\]gems[\/\\]}
+
+    # @!constant DEFAULT_MAX_LENGTH
+    #   @return [Integer] The default maximum length for formatted exception messages.
+    DEFAULT_MAX_LENGTH = 2500
+
+    # @!constant RSPEC_SKIP_LIST
+    #   @return [Set<Symbol>] A set of RSpec-specific instance variables to skip.
+    RSPEC_SKIP_LIST = Set.new([
+                                :@fixture_cache,
+                                :@fixture_cache_key,
+                                :@fixture_connection_pools,
+                                :@connection_subscriber,
+                                :@saved_pool_configs,
+                                :@loaded_fixtures,
+                                :@matcher_definitions,
+                              ])
+
+    # @!constant RAILS_SKIP_LIST
+    #   @return [Set<Symbol>] A set of Rails-specific instance variables to skip.
+    RAILS_SKIP_LIST = Set.new([
+                                :@new_record,
+                                :@attributes,
+                                :@association_cache,
+                                :@readonly,
+                                :@previously_new_record,
+                                :@destroyed,
+                                :@marked_for_destruction,
+                                :@destroyed_by_association,
+                                :@primary_key,
+                                :@strict_loading,
+                                :@strict_loading_mode,
+                                :@mutations_before_last_save,
+                                :@mutations_from_database
+                              ])
+
+    # Gets or sets the maximum length for the formatted exception message.
+    #
+    # @param value [Integer, nil] The desired maximum length. If `nil`, returns the current value.
+    # @return [Integer] The maximum length for the formatted message.
+    def max_length(value = nil)
+      if value.nil?
+        @max_length ||= DEFAULT_MAX_LENGTH
+      else
+        @max_length = value
+      end
+      @max_length
+    end
+
+    # Gets or sets whether to capture RSpec `let` variables.
+    #
+    # @param value [Boolean, nil] The desired state. If `nil`, returns the current value.
+    # @return [Boolean] Whether RSpec `let` variables are being captured.
+    def capture_let_variables(value = nil)
+      if value.nil?
+        @capture_let_variables = @capture_let_variables.nil? ? true : @capture_let_variables
+      else
+        @capture_let_variables = value
+      end
+      @capture_let_variables
+    end
+
+    # Retrieves the current skip list, initializing it with default values if not already set.
+    #
+    # @return [Set<Symbol>] The current skip list.
+    def skip_list
+      @skip_list ||= default_skip_list
+    end
+
+    # Initializes the default skip list by merging Rails and RSpec specific variables.
+    #
+    # @return [Set<Symbol>] The default skip list.
+    def default_skip_list
+      Set.new(RAILS_SKIP_LIST).merge(RSPEC_SKIP_LIST)
+    end
+
+    # Adds variables to the skip list to exclude them from binding information.
+    #
+    # @param vars [Symbol] The variable names to add to the skip list.
+    # @return [Set<Symbol>] The updated skip list.
+    def add_to_skip_list(*vars)
+      skip_list.merge(vars)
+    end
+
+    # Enhances the exception handling by setting up tracing and configuration options.
+    #
+    # @param enabled [Boolean] Whether to enable EnhancedErrors.
+    # @param debug [Boolean] Whether to enable debug mode.
+    # @param options [Hash] Additional configuration options.
+    # @yield [void] A block for additional configuration.
+    # @return [void]
+    def enhance!(enabled: true, debug: false, **options, &block)
+      @output_format = nil
+      @eligible_for_capture = nil
+      @original_global_variables = nil
+      if enabled == false
+        @original_global_variables = nil
+        @enabled = false
+        @trace.disable if @trace
+      else
+        @enabled = true
+        @debug = debug
+        @original_global_variables = global_variables
+
+        options.each do |key, value|
+          setter_method = "#{key}="
+          if respond_to?(setter_method)
+            send(setter_method, value)
+          elsif respond_to?(key)
+            send(key, value)
+          else
+            # Ignore unknown options or handle as needed
+          end
+        end
+
+        @config_block = block_given? ? block : nil
+        instance_eval(&@config_block) if @config_block
+
+        start_tracing
+      end
+    end
+
+    # Sets or retrieves the eligibility criteria for capturing exceptions.
+    #
+    # @yieldparam exception [Exception] The exception to evaluate.
+    # @return [Proc] The current eligibility proc.
+    def eligible_for_capture(&block)
+      if block_given?
+        @eligible_for_capture = block
+      else
+        @eligible_for_capture ||= method(:default_eligible_for_capture)
+      end
+    end
+
+    # Sets or retrieves the hook to modify binding information upon capture.
+    #
+    # @yieldparam binding_info [Hash] The binding information captured.
+    # @return [Proc] The current on_capture hook.
+    def on_capture(&block)
+      if block_given?
+        @on_capture_hook = block
+      else
+        @on_capture_hook ||= method(:default_on_capture)
+      end
+    end
+
+    # Sets the on_capture hook.
+    #
+    # @param value [Proc] The proc to set as the on_capture hook.
+    # @return [Proc] The newly set on_capture hook.
+    def on_capture=(value)
+      self.on_capture_hook = value
+    end
+
+    # Sets or retrieves the hook to modify formatted exception messages.
+    #
+    # @yieldparam formatted_string [String] The formatted exception message.
+    # @return [Proc] The current on_format hook.
+    def on_format(&block)
+      if block_given?
+        @on_format_hook = block
+      else
+        @on_format_hook ||= method(:default_on_format)
+      end
+    end
+
+    # Sets the on_format hook.
+    #
+    # @param value [Proc] The proc to set as the on_format hook.
+    # @return [Proc] The newly set on_format hook.
+    def on_format=(value)
+      @on_format_hook = value
+    end
+
+    # Formats the captured binding information into a string based on the specified format.
+    #
+    # @param captured_bindings [Array<Hash>] The array of captured binding information.
+    # @param output_format [Symbol] The format to use for output (:json, :plaintext, :terminal).
+    # @return [String] The formatted exception message.
+    def format(captured_bindings = [], output_format = get_default_format_for_environment)
+      result = binding_infos_array_to_string(captured_bindings, output_format)
+      if @on_format_hook
+        result = @on_format_hook.call(result)
+      else
+        result = default_on_format(result)
+      end
+      result
+    end
+
+    # Converts an array of binding information hashes into a formatted string.
+    #
+    # @param captured_bindings [Array<Hash>] The array of binding information.
+    # @param format [Symbol] The format to use (:json, :plaintext, :terminal).
+    # @return [String] The formatted string representation of the binding information.
+    def binding_infos_array_to_string(captured_bindings, format = :terminal)
+      case format
+      when :json
+        Colors.enabled = false
+        JSON.pretty_generate(captured_bindings)
+      when :plaintext
+        Colors.enabled = false
+        captured_bindings.map { |binding_info| binding_info_string(binding_info) }.join("\n")
+      when :terminal
+        Colors.enabled = true
+        captured_bindings.map { |binding_info| binding_info_string(binding_info) }.join("\n")
+      else
+        Colors.enabled = false
+        captured_bindings.map { |binding_info| binding_info_string(binding_info) }.join("\n")
+      end
+    end
+
+    # Determines the default output format based on the current environment.
+    #
+    # @return [Symbol] The default format (:json, :plaintext, :terminal).
+    def get_default_format_for_environment
+      return @output_format unless @output_format.nil?
+      env = ENV['RAILS_ENV'] || ENV['RACK_ENV'] || 'development'
+      @output_format = case env
+                       when 'development', 'test'
+                         if running_in_ci?
+                           :plaintext
+                         else
+                           :terminal
+                         end
+                       when 'production'
+                         :json
+                       else
+                         :terminal
+                       end
+    end
+
+    # Checks if the code is running in a Continuous Integration (CI) environment.
+    #
+    # @return [Boolean] `true` if running in CI, otherwise `false`.
+    def running_in_ci?
+      return @running_in_ci if defined?(@running_in_ci)
+      ci_env_vars = {
+        'CI' => ENV['CI'],
+        'JENKINS' => ENV['JENKINS'],
+        'GITHUB_ACTIONS' => ENV['GITHUB_ACTIONS'],
+        'CIRCLECI' => ENV['CIRCLECI'],
+        'TRAVIS' => ENV['TRAVIS'],
+        'APPVEYOR' => ENV['APPVEYOR'],
+        'GITLAB_CI' => ENV['GITLAB_CI']
+      }
+      @running_in_ci = ci_env_vars.any? { |_, value| value.to_s.downcase == 'true' }
+    end
+
+    # Applies the skip list to the captured binding information, excluding specified variables.
+    #
+    # @param binding_info [Hash] The binding information to filter.
+    # @return [Hash] The filtered binding information.
+    def apply_skip_list(binding_info)
+      unless @debug
+        variables = binding_info[:variables]
+        variables[:instances]&.reject! { |var, _| skip_list.include?(var) || var.to_s.start_with?('@__') }
+        variables[:locals]&.reject! { |var, _| skip_list.include?(var) }
+        variables[:globals]&.reject! { |var, _| skip_list.include?(var) }
+      end
+      binding_info
+    end
+
+    # Validates the format of the captured binding information.
+    #
+    # @param binding_info [Hash] The binding information to validate.
+    # @return [Hash, nil] The validated binding information or `nil` if invalid.
+    def validate_binding_format(binding_info)
+      unless binding_info.keys.include?(:capture_type) && binding_info[:variables].is_a?(Hash)
+        puts "Invalid binding_info format."
+        return nil
+      end
+      binding_info
+    end
+
+    # Formats a single binding information hash into a string with colorization.
+    #
+    # @param binding_info [Hash] The binding information to format.
+    # @return [String] The formatted string.
+    def binding_info_string(binding_info)
+      result = "\n#{Colors.green("#{binding_info[:capture_type].capitalize}: ")}#{Colors.blue(binding_info[:source])}"
+
+      result += method_and_args_desc(binding_info[:method_and_args])
+
+      variables = binding_info[:variables] || {}
+
+      if variables[:locals] && !variables[:locals].empty?
+        result += "\n#{Colors.green('Locals:')}\n#{variable_description(variables[:locals])}"
+      end
+
+      instance_vars_to_display = variables[:instances] || {}
+
+
+      if instance_vars_to_display && !instance_vars_to_display.empty?
+        result += "\n#{Colors.green('Instances:')}\n#{variable_description(instance_vars_to_display)}"
+      end
+
+      if variables[:lets] && !variables[:lets].empty?
+        result += "\n#{Colors.green('Let Variables:')}\n#{variable_description(variables[:lets])}"
+      end
+
+      if variables[:globals] && !variables[:globals].empty?
+        result += "\n#{Colors.green('Globals:')}\n#{variable_description(variables[:globals])}"
+      end
+
+      if result.length > max_length
+        result = result[0...max_length] + "... (truncated)"
+      end
+      result + "\n\n"
+    end
+
+    private
+
+    # Starts the TracePoint for capturing exceptions based on configured events.
+    #
+    # @return [void]
+    def start_tracing
+      return if @trace && @trace.enabled?
+
+      events = [:raise]
+      events << :rescue if Gem::Version.new(RUBY_VERSION) >= Gem::Version.new('3.3.0')
+
+      @trace = TracePoint.new(*events) do |tp|
+        exception = tp.raised_exception
+        capture_me = EnhancedErrors.eligible_for_capture.call(exception)
+
+        next unless capture_me
+
+        next if Thread.current[:enhanced_errors_processing]
+        Thread.current[:enhanced_errors_processing] = true
+
+        exception = tp.raised_exception
+        binding_context = tp.binding
+
+        unless exception.instance_variable_defined?(:@binding_infos)
+          exception.instance_variable_set(:@binding_infos, [])
+          exception.extend(ErrorEnhancements)
+        end
+
+        method_name = tp.method_id
+        method_and_args = {
+          object_name: determine_object_name(tp, method_name),
+          args: extract_arguments(tp, method_name)
+        }
+
+        locals = binding_context.local_variables.map { |var|
+          [var, binding_context.local_variable_get(var)]
+        }.to_h
+
+        instance_vars = binding_context.receiver.instance_variables
+
+        instances = instance_vars.map { |var|
+          [var, (binding_context.receiver.instance_variable_get(var) rescue "#<Error getting instance variable: #{$!.message}>")]
+        }.to_h
+
+        # Extract 'let' variables from :@__memoized (RSpec specific)
+        lets = {}
+        if capture_let_variables && instance_vars.include?(:@__memoized)
+          outer_memoized = binding_context.receiver.instance_variable_get(:@__memoized)
+          memoized = outer_memoized.instance_variable_get(:@memoized) if outer_memoized.respond_to?(:instance_variable_get)
+          if memoized.is_a?(Hash)
+            lets = memoized&.transform_keys(&:to_sym)
+          end
+        end
+
+        globals = {}
+        # Capture global variables
+        if @debug
+          globals = (global_variables - @original_global_variables).map { |var|
+            [var, get_global_variable_value(var)]
+          }.to_h
+          puts "Global Variables: #{globals.inspect}"
+        end
+
+        capture_type = tp.event.to_s  # 'raise' or 'rescue'
+        location = "#{tp.path}:#{tp.lineno}"
+
+        binding_info = {
+          source: location,
+          object: tp.self,
+          library: !!GEMS_REGEX.match?(location),
+          method_and_args: method_and_args,
+          test_name: test_name,
+          variables: {
+            locals: locals,
+            instances: instances,
+            lets: lets,
+            globals: globals
+          },
+          exception: exception.class.name,
+          capture_type: capture_type
+        }
+
+        if on_capture_hook
+          binding_info = on_capture_hook.call(binding_info)
+        else
+          binding_info = default_on_capture(binding_info)
+        end
+
+        binding_info = validate_binding_format(binding_info)
+
+        if binding_info
+          exception.instance_variable_get(:@binding_infos) << binding_info
+        else
+          puts "Invalid binding_info returned from on_capture, skipping."
+        end
+      ensure
+        Thread.current[:enhanced_errors_processing] = false
+      end
+
+      @trace.enable
+    end
+
+    def test_name
+      return RSpec&.current_example&.full_description if defined?(RSpec)
+      nil
+    end
+
+    # Extracts method arguments from the TracePoint binding.
+    #
+    # @param tp [TracePoint] The current TracePoint.
+    # @param method_name [Symbol] The name of the method.
+    # @return [String] A string representation of the method arguments.
+    def extract_arguments(tp, method_name)
+      return '' unless method_name
+      begin
+        bind = tp.binding
+        unbound_method = tp.defined_class.instance_method(method_name)
+        method_obj = unbound_method.bind(tp.self)
+        parameters = method_obj.parameters
+        locals = bind.local_variables
+
+        return parameters.map do |(type, name)|
+          value = locals.include?(name) ? bind.local_variable_get(name) : nil
+          "#{name}=#{value.inspect}"
+        rescue => e
+          "#{name}=#<Error getting argument: #{e.message}>"
+        end.join(", ")
+      end
+
+      rescue => e
+      "#<Error getting arguments: #{e.message}>"
+    end
+
+
+    # Determines the object name based on the TracePoint and method name.
+    #
+    # @param tp [TracePoint] The current TracePoint.
+    # @param method_name [Symbol] The name of the method.
+    # @return [String] The formatted object name.
+    def determine_object_name(tp, method_name)
+      if tp.self.is_a?(Class) && tp.self.singleton_class == tp.defined_class
+        "#{tp.self}.#{method_name}"
+      else
+        "#{tp.self.class.name}##{method_name}"
+      end
+    rescue => e
+      "#<Error inspecting value: #{e.message}>"
+    end
+
+    # Retrieves the value of a global variable by its name.
+    #
+    # @param var [Symbol] The name of the global variable.
+    # @return [Object, String] The value of the global variable or an error message.
+    def get_global_variable_value(var)
+      begin
+        var.is_a?(Symbol) ? eval("#{var}") : nil
+      rescue => e
+        "#<Error getting value: #{e.message}>"
+      end
+    end
+
+    # Generates a description for method and arguments.
+    #
+    # @param method_info [Hash] Information about the method and its arguments.
+    # @return [String] The formatted description.
+    def method_and_args_desc(method_info)
+      return '' unless method_info[:object_name] != '' || method_info[:args]&.length.to_i > 0
+      arg_str = method_info[:args]
+      arg_str = "(#{arg_str})" if arg_str != ""
+      str = method_info[:object_name] + arg_str
+      "\n#{Colors.green('Method: ')}#{Colors.blue(str)}\n"
+    end
+
+    # Generates a formatted description for a set of variables.
+    #
+    # @param vars_hash [Hash] A hash of variable names and their values.
+    # @return [String] The formatted variables description.
+    def variable_description(vars_hash)
+      vars_hash.map do |name, value|
+        "  #{Colors.purple(name)}: #{format_variable(value)}\n"
+      end.join
+    end
+
+    # Formats a variable for display, using `awesome_print` if available and enabled.
+    #
+    # @param variable [Object] The variable to format.
+    # @return [String] The formatted variable.
+    def format_variable(variable)
+      (awesome_print_available? && Colors.enabled?) ? variable.ai : variable.inspect
+    end
+
+    # Checks if the `AwesomePrint` gem is available.
+    #
+    # @return [Boolean] `true` if `AwesomePrint` is available, otherwise `false`.
+    def awesome_print_available?
+      return @awesome_print_available unless @awesome_print_available.nil?
+      @awesome_print_available = defined?(AwesomePrint)
+    end
+
+    # Default implementation for the on_format hook.
+    #
+    # @param string [String] The formatted exception message.
+    # @return [String] The unmodified exception message.
+    def default_on_format(string)
+      string
+    end
+
+    # Default implementation for the on_capture hook, applying the skip list.
+    #
+    # @param binding_info [Hash] The captured binding information.
+    # @return [Hash] The filtered binding information.
+    def default_on_capture(binding_info)
+      # Use this to clean up the captured bindings
+      EnhancedErrors.apply_skip_list(binding_info)
+    end
+
+    # Default eligibility check for capturing exceptions.
+    #
+    # @param exception [Exception] The exception to evaluate.
+    # @return [Boolean] `true` if the exception should be captured, otherwise `false`.
+    def default_eligible_for_capture(exception)
+      true
+    end
+
+    @enabled = false
+  end
+end

data/lib/error_enhancements.rb

@@ -0,0 +1,53 @@
+module ErrorEnhancements
+  def message
+    original_message = super()
+    "#{original_message}#{variables_message}"
+  rescue => e
+    puts "Error in message method: #{e.message}"
+    original_message
+  end
+
+  def variables_message
+    @variables_message ||= begin
+                             bindings_of_interest = []
+                             if defined?(@binding_infos) && @binding_infos && !@binding_infos.empty?
+                               bindings_of_interest = select_binding_infos(@binding_infos)
+                             end
+                             EnhancedErrors.format(bindings_of_interest)
+                           rescue => e
+                             puts "Error in variables_message: #{e.message}"
+                             ""
+                           end
+  end
+
+  private
+
+  def select_binding_infos(binding_infos)
+    # Preference:
+    # Grab the first raise binding that isn't a library (gem) binding.
+    # If there are only library bindings, grab the first one.
+    # Grab the last rescue binding if we have one
+
+    bindings_of_interest = []
+    binding_infos.each do |info|
+      if info[:capture_type] == 'raise' && !info[:library]
+        bindings_of_interest << info
+        break
+      end
+    end
+
+    if bindings_of_interest.empty?
+      bindings_of_interest << binding_infos.first if binding_infos.first
+    end
+
+    # find the last rescue binding if there is one
+    binding_infos.reverse.each do |info|
+      if info[:capture_type] == 'rescue'
+        bindings_of_interest << info
+        break
+      end
+    end
+    bindings_of_interest
+  end
+
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: enhanced_errors
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Eric Beland
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-10-22 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: 3.4.0
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">"
+      - !ruby/object:Gem::Version
+        version: 3.4.0
+description: With no extra dependencies, and using only Ruby's built-in TracePoint,
+  EnhancedErrors will automatically enhance your errors with messages containing variable
+  values from the moment they were raised.
+email:
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- LICENSE
+- README.md
+- benchmark/benchmark.rb
+- benchmark/stackprofile.rb
+- doc/images/enhance.png
+- doc/images/enhanced-error.png
+- doc/images/enhanced-spec.png
+- enhanced_errors.gemspec
+- examples/division_by_zero_example.rb
+- examples/example_spec.rb
+- lib/binding.rb
+- lib/colors.rb
+- lib/enhanced_errors.rb
+- lib/error_enhancements.rb
+homepage: https://github.com/ericbeland/enhanced_errors.
+licenses: []
+metadata:
+  homepage_uri: https://github.com/ericbeland/enhanced_errors.
+  source_code_uri: https://github.com/ericbeland/enhanced_errors
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.0.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.3.26
+signing_key:
+specification_version: 4
+summary: Automatically enhance your errors with messages containing variable values
+  from the moment they were raised.
+test_files: []