object_tracer 1.0.0

data/lib/object_tracer/configuration.rb

@@ -0,0 +1,34 @@
+class ObjectTracer
+  class Configuration
+    DEFAULTS = {
+      filter_by_paths: [],
+      exclude_by_paths: [],
+      with_trace_to: 50,
+      event_type: :return,
+      hijack_attr_methods: false,
+      track_as_records: false,
+      ignore_private: false,
+      only_private: false
+    }.merge(ObjectTracer::Output::DEFAULT_OPTIONS)
+
+    def initialize
+      @options = {}
+
+      DEFAULTS.each do |key, value|
+        @options[key] = value
+      end
+    end
+
+    def [](key)
+      @options[key]
+    end
+
+    def []=(key, value)
+      @options[key] = value
+    end
+  end
+
+  def self.config
+    @config ||= Configuration.new
+  end
+end

data/lib/object_tracer/exceptions.rb

@@ -0,0 +1,16 @@
+class ObjectTracer
+  class Exception < StandardError
+  end
+
+  class NotAnActiveRecordInstanceError < Exception
+    def initialize(object)
+      super("target object should be an instance of ActiveRecord::Base, got #{object}")
+    end
+  end
+
+  class NotAClassError < Exception
+    def initialize(object)
+      super("target object should be a class, got #{object}")
+    end
+  end
+end

data/lib/object_tracer/manageable.rb

@@ -0,0 +1,37 @@
+class ObjectTracer
+  module Manageable
+
+    def suspend_new
+      @suspend_new
+    end
+
+    # list all registered devices
+    def devices
+      @devices
+    end
+
+    # disable given device and remove it from registered list
+    def delete_device(device)
+      device.trace_point&.disable
+      @devices -= [device]
+    end
+
+    # stops all registered devices and remove them from registered list
+    def stop_all!
+      @devices.each(&:stop!)
+    end
+
+    # suspend enabling new trace points
+    # user can still create new Device instances, but they won't be functional
+    def suspend_new!
+      @suspend_new = true
+    end
+
+    # reset everything to clean state and disable all devices
+    def reset!
+      @suspend_new = false
+      stop_all!
+    end
+  end
+end
+

data/lib/object_tracer/method_hijacker.rb

@@ -0,0 +1,55 @@
+class ObjectTracer
+  class MethodHijacker
+    attr_reader :target
+
+    def initialize(target)
+      @target = target
+    end
+
+    def hijack_methods!
+      target.methods.each do |method_name|
+        if is_writer_method?(method_name)
+          redefine_writer_method!(method_name)
+        elsif is_reader_method?(method_name)
+          redefine_reader_method!(method_name)
+        end
+      end
+    end
+
+    private
+
+    def is_writer_method?(method_name)
+      has_definition_source?(method_name) && method_name.match?(/\w+=/) && target.method(method_name).source.match?(/attr_writer|attr_accessor/)
+    rescue MethodSource::SourceNotFoundError
+      false
+    end
+
+    def is_reader_method?(method_name)
+      has_definition_source?(method_name) && target.method(method_name).source.match?(/attr_reader|attr_accessor/)
+    rescue MethodSource::SourceNotFoundError
+      false
+    end
+
+    def has_definition_source?(method_name)
+      target.method(method_name).source_location
+    end
+
+    def redefine_writer_method!(method_name)
+      ivar_name = "@#{method_name.to_s.sub("=", "")}"
+
+      target.instance_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{method_name}(val)
+          #{ivar_name} = val
+        end
+      RUBY
+    end
+
+    def redefine_reader_method!(method_name)
+      target.instance_eval <<-RUBY, __FILE__, __LINE__ + 1
+        def #{method_name}
+          @#{method_name}
+        end
+      RUBY
+    end
+  end
+end

data/lib/object_tracer/output.rb

@@ -0,0 +1,41 @@
+require "logger"
+require "object_tracer/output/payload_wrapper"
+require "object_tracer/output/writer"
+
+class ObjectTracer
+  module Output
+    DEFAULT_OPTIONS = {
+      inspect: false,
+      colorize: true,
+      log_file: "/tmp/object_tracer.log"
+    }
+
+    module Helpers
+      def and_write(payload_method = nil, options: {}, &block)
+        and_output(payload_method, options: options, logger: Logger.new(options[:log_file]), &block)
+      end
+
+      def and_print(payload_method = nil, options: {}, &block)
+        and_output(payload_method, options: options, logger: Logger.new($stdout), &block)
+      end
+
+      def and_output(payload_method = nil, options: {}, logger:, &block)
+        output_block = generate_output_block(payload_method, block)
+        @output_writer = Writer.new(options: options, output_block: output_block, logger: logger)
+        self
+      end
+
+      private
+
+      def generate_output_block(payload_method, block)
+        if block
+          block
+        elsif payload_method
+          -> (output_payload, output_options) { output_payload.send(payload_method, output_options) }
+        else
+          raise "need to provide either a payload method name or a block"
+        end
+      end
+    end
+  end
+end

data/lib/object_tracer/output/payload_wrapper.rb

@@ -0,0 +1,186 @@
+require "pastel"
+
+class ObjectTracer
+  module Output
+    class PayloadWrapper
+      UNDEFINED = "[undefined]"
+      PRIVATE_MARK = " (private)"
+
+      PASTEL = Pastel.new
+      PASTEL.alias_color(:orange, :bright_red, :bright_yellow)
+
+      ObjectTracer::Payload::ATTRS.each do |attr|
+        define_method attr do |options = {}|
+          @payload.send(attr)
+        end
+      end
+
+      alias :is_private_call? :is_private_call
+
+      def method_head
+        @payload.method_head
+      end
+
+      def location(options = {})
+        @payload.location(options)
+      end
+
+      alias :raw_arguments :arguments
+      alias :raw_return_value :return_value
+
+      def initialize(payload)
+        @payload = payload
+      end
+
+      def method_name(options = {})
+        name = ":#{@payload.method_name}"
+
+        name += " [#{tag}]" if tag
+        name += PRIVATE_MARK if is_private_call?
+
+        name
+      end
+
+      def arguments(options = {})
+        generate_string_result(raw_arguments, options[:inspect])
+      end
+
+      def return_value(options = {})
+        generate_string_result(raw_return_value, options[:inspect])
+      end
+
+      PAYLOAD_ATTRIBUTES = {
+        method_name: {symbol: "", color: :bright_blue},
+        location: {symbol: "from:", color: :green},
+        return_value: {symbol: "=>", color: :magenta},
+        arguments: {symbol: "<=", color: :orange},
+        ivar_changes: {symbol: "changes:\n", color: :blue},
+        defined_class: {symbol: "#", color: :yellow}
+      }
+
+      PAYLOAD_ATTRIBUTES.each do |attribute, attribute_options|
+        color = attribute_options[:color]
+
+        alias_method "original_#{attribute}".to_sym, attribute
+
+        # regenerate attributes with `colorize: true` support
+        define_method attribute do |options = {}|
+          call_result = send("original_#{attribute}", options).to_s
+
+          if options[:colorize]
+            PASTEL.send(color, call_result)
+          else
+            call_result
+          end
+        end
+
+        define_method "#{attribute}_with_color" do |options = {}|
+          send(attribute, options.merge(colorize: true))
+        end
+
+        PAYLOAD_ATTRIBUTES.each do |and_attribute, and_attribute_options|
+          next if and_attribute == attribute
+
+          define_method "#{attribute}_and_#{and_attribute}" do |options = {}|
+            "#{send(attribute, options)} #{and_attribute_options[:symbol]} #{send(and_attribute, options)}"
+          end
+
+          define_method "#{attribute}_and_#{and_attribute}_with_color" do |options = {}|
+            send("#{attribute}_and_#{and_attribute}", options.merge(colorize: true))
+          end
+        end
+      end
+
+      def passed_at(options = {})
+        with_method_head = options.fetch(:with_method_head, false)
+        arg_name = raw_arguments.keys.detect { |k| raw_arguments[k] == target }
+
+        return unless arg_name
+
+        arg_name = ":#{arg_name}"
+        arg_name = PASTEL.orange(arg_name) if options[:colorize]
+        msg = "Passed as #{arg_name} in '#{defined_class(options)}##{method_name(options)}' at #{location(options)}\n"
+        msg += "  > #{method_head}\n" if with_method_head
+        msg
+      end
+
+      def detail_call_info(options = {})
+        <<~MSG
+        #{method_name_and_defined_class(options)}
+            from: #{location(options)}
+            <= #{arguments(options)}
+            => #{return_value(options)}
+
+        MSG
+      end
+
+      def ivar_changes(options = {})
+        @payload.ivar_changes.map do |ivar, value_changes|
+          before = generate_string_result(value_changes[:before], options[:inspect])
+          after = generate_string_result(value_changes[:after], options[:inspect])
+
+          if options[:colorize]
+            ivar = PASTEL.orange(ivar.to_s)
+            before = PASTEL.bright_blue(before.to_s)
+            after = PASTEL.bright_blue(after.to_s)
+          end
+
+          "      #{ivar}: #{before} => #{after}"
+        end.join("\n")
+      end
+
+      def call_info_with_ivar_changes(options = {})
+        <<~MSG
+        #{method_name_and_defined_class(options)}
+            from: #{location(options)}
+            changes:
+        #{ivar_changes(options)}
+
+        MSG
+      end
+
+      private
+
+      def generate_string_result(obj, inspect)
+        case obj
+        when Array
+          array_to_string(obj, inspect)
+        when Hash
+          hash_to_string(obj, inspect)
+        when UNDEFINED
+          UNDEFINED
+        when String
+          "\"#{obj}\""
+        when nil
+          "nil"
+        else
+          inspect ? obj.inspect : obj.to_s
+        end
+      end
+
+      def array_to_string(array, inspect)
+        elements_string = array.map do |elem|
+          generate_string_result(elem, inspect)
+        end.join(", ")
+        "[#{elements_string}]"
+      end
+
+      def hash_to_string(hash, inspect)
+        elements_string = hash.map do |key, value|
+          "#{key.to_s}: #{generate_string_result(value, inspect)}"
+        end.join(", ")
+        "{#{elements_string}}"
+      end
+
+      def obj_to_string(element, inspect)
+        to_string_method = inspect ? :inspect : :to_s
+
+        if !inspect && element.is_a?(String)
+          "\"#{element}\""
+        else
+          element.send(to_string_method)
+        end
+      end
+    end
+  end
+end

data/lib/object_tracer/output/writer.rb

@@ -0,0 +1,22 @@
+class ObjectTracer
+  module Output
+    class Writer
+      def initialize(options:, output_block:, logger:)
+        @options = options
+        @output_block = output_block
+        @logger = logger
+      end
+
+      def write!(payload)
+        output = generate_output(payload)
+        @logger << output
+      end
+
+      private
+
+      def generate_output(payload)
+        @output_block.call(PayloadWrapper.new(payload), @options)
+      end
+    end
+  end
+end

data/lib/object_tracer/payload.rb

@@ -0,0 +1,40 @@
+class ObjectTracer
+  class Payload
+    ATTRS = [
+      :target, :receiver, :method_name, :method_object, :arguments, :return_value, :filepath, :line_number,
+      :defined_class, :trace, :tag, :tp, :ivar_changes, :is_private_call
+    ]
+
+    attr_accessor(*ATTRS)
+
+    alias :is_private_call? :is_private_call
+
+    def initialize(
+      target:, receiver:, method_name:, method_object:, arguments:, return_value:, filepath:, line_number:,
+      defined_class:, trace:, tag:, tp:, is_private_call:
+    )
+      @target = target
+      @receiver = receiver
+      @method_name = method_name
+      @method_object = method_object
+      @arguments = arguments
+      @return_value = return_value
+      @filepath = filepath
+      @line_number = line_number
+      @defined_class = defined_class
+      @trace = trace
+      @tag = tag
+      @tp = tp
+      @ivar_changes = {}
+      @is_private_call = is_private_call
+    end
+
+    def method_head
+      method_object.source.strip if method_object.source_location
+    end
+
+    def location(options = {})
+      "#{filepath}:#{line_number}"
+    end
+  end
+end

data/lib/object_tracer/trackable.rb

@@ -0,0 +1,133 @@
+class ObjectTracer
+  module Trackable
+    def tap_init!(object, options = {}, &block)
+      ObjectTracer::Trackers::InitializationTracker.new(options, &block).track(object)
+    end
+
+    def tap_passed!(object, options = {}, &block)
+      ObjectTracer::Trackers::PassedTracker.new(options, &block).track(object)
+    end
+
+    def tap_assoc!(object, options = {}, &block)
+      ObjectTracer::Trackers::AssociactionCallTracker.new(options, &block).track(object)
+    end
+
+    def tap_on!(object, options = {}, &block)
+      ObjectTracer::Trackers::MethodCallTracker.new(options, &block).track(object)
+    end
+
+    def tap_mutation!(object, options = {}, &block)
+      ObjectTracer::Trackers::MutationTracker.new(options, &block).track(object)
+    end
+
+    [:calls, :traces, :mutations].each do |subject|
+      [:print, :write].each do |output_action|
+        helper_method_name = "#{output_action}_#{subject}"
+
+        define_method helper_method_name do |target, options = {}|
+          send("output_#{subject}", target, options, output_action: "and_#{output_action}")
+        end
+
+        define_method "with_#{helper_method_name}" do |options = {}|
+          send(helper_method_name, self, options)
+          self
+        end
+
+        define_method "#{output_action}_instance_#{subject}" do |target_klass, options = {}|
+          collection_proxy = AsyncCollectionProxy.new
+
+          tap_init!(target_klass, options.merge(force_recording: true)) do |payload|
+            collection_proxy << send(helper_method_name, payload.return_value, options)
+          end
+
+          collection_proxy
+        end
+      end
+    end
+
+    private
+
+    def output_calls(target, options = {}, output_action:)
+      device_options, output_options = separate_options(options)
+
+      tap_on!(target, device_options).send(output_action, options: output_options) do |output_payload, output_options|
+        output_payload.detail_call_info(output_options)
+      end
+    end
+
+    def output_traces(target, options = {}, output_action:)
+      device_options, output_options = separate_options(options)
+      device_options[:event_type] = :call
+
+      device_1 = tap_on!(target, device_options).send(output_action, options: output_options) do |output_payload, output_options|
+        "Called #{output_payload.method_name_and_location(output_options)}\n"
+      end
+      device_2 = tap_passed!(target, device_options).send(output_action, options: output_options) do |output_payload, output_options|
+        output_payload.passed_at(output_options)
+      end
+      CollectionProxy.new([device_1, device_2])
+    end
+
+    def output_mutations(target, options = {}, output_action:)
+      device_options, output_options = separate_options(options)
+
+      tap_mutation!(target, device_options).send(output_action, options: output_options) do |output_payload, output_options|
+        output_payload.call_info_with_ivar_changes(output_options)
+      end
+    end
+
+    def separate_options(options)
+      output_options = Output::DEFAULT_OPTIONS.keys.each_with_object({}) do |key, hash|
+        hash[key] = options.fetch(key, ObjectTracer.config[key])
+        options.delete(key)
+      end
+
+      [options, output_options]
+    end
+
+    # CollectionProxy delegates chained actions to multiple devices
+    class CollectionProxy
+      CHAINABLE_ACTIONS = [:stop!, :stop_when, :with]
+
+      def initialize(devices)
+        @devices = devices
+      end
+
+      CHAINABLE_ACTIONS.each do |method|
+        define_method method do |&block|
+          @devices.each do |device|
+            device.send(method, &block)
+          end
+        end
+      end
+    end
+
+    # AsyncCollectionProxy delegates chained actions to multiple device "asyncronously"
+    # when we use tapping methods like `tap_init!` to create sub-devices
+    # we need to find a way to pass the chained actions to every sub-device that's created
+    # and this can only happen asyncronously as we won't know when'll that happen
+    class AsyncCollectionProxy < CollectionProxy
+      def initialize(devices = [])
+        super
+        @blocks = {}
+      end
+
+      CHAINABLE_ACTIONS.each do |method|
+        define_method method do |&block|
+          super(&block)
+          @blocks[method] = block
+        end
+      end
+
+      def <<(device)
+        @devices << device
+
+        @blocks.each do |method, block|
+          device.send(method, &block)
+        end
+      end
+    end
+  end
+end
+
+include ObjectTracer::Trackable