tapping_device 0.5.3 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9311ddb749d3c7bf09306161da25191c0de47734dea77f645f5d5af62a55d802
-  data.tar.gz: 4df7c9fef5c3a3a2b3852b5b4f4db31ec071149dd19b3fceb1df6f6b1ac191e8
+  metadata.gz: d8adc4b6842ade7721eafaf72e9b94c8a6a852c1f9f9beebdf2556b20cef6d4a
+  data.tar.gz: ab22b319f6468837e92f851f00f863cf732dd3c0cc73e286d5f9569d00c34db6
 SHA512:
-  metadata.gz: deaece3e6096551df6fe3c7eb492f6049e72b32f7e19b7a8d4067f8d5a6dc9b6fe56a41d3bd9855220ae11c8adcc377cd188f51c043835845be5c2d9250bc6d1
-  data.tar.gz: 057766f277605fb3e80bd2797ee1256f0f6d81fbca56c95226199a72c7e14565dc353292d06711847e257d2f552e9eb3ddcd076ec35f1abd3aaf30cc9f686f5c
+  metadata.gz: 992f31b79a3c0a8abc8471ae643f02586cf76d505da493cfe66b37338781251c3dfdba43a158776431c93a342e8b9a02baff78118b71c679aba2f9114c65077c
+  data.tar.gz: cad971d539041804a9860225f17ae23754dc46ea6fa5b7dc15d674e5189c081dd4f6f2602eeea9c27e616fb1b959126fe452ef5f641e249d73392782b17a3c2c

data/.github/workflows/ruby.yml

@@ -1,6 +1,11 @@
 name: Ruby
 
-on: [push, pull_request]
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - master
+  pull_request:
 
 jobs:
   test:
@@ -8,9 +13,12 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        rails_version: ['5.2', '6']
-        ruby_version: ['2.5', '2.6']
+        rails_version: ['5.2', '6.0.0', '6.1.0']
+        ruby_version: ['2.7', '3.0']
         os: [ubuntu-latest]
+        exclude:
+          - ruby_version: '3.0'
+            rails_version: '5.2'
     steps:
     - uses: actions/checkout@v1
 
@@ -34,7 +42,9 @@ jobs:
         bundle install --jobs 4 --retry 3
 
     - name: Run test with Rails ${{ matrix.rails_version }}
-      run: bundle exec rake
+      env:
+        RAILS_VERSION: ${{ matrix.rails_version }}
+      run: make test
 
     - name: Publish Test Coverage
       uses: paambaati/codeclimate-action@v2.6.0

data/.gitignore

@@ -7,5 +7,7 @@
 /spec/reports/
 /tmp/
 
+Gemfile.lock
+
 # rspec failure tracking
 .rspec_status

data/.ruby-version

@@ -1 +1 @@
-2.6.5
+3.0.1

data/CHANGELOG.md

@@ -2,15 +2,84 @@
 
 ## [Unreleased](https://github.com/st0012/tapping_device/tree/HEAD)
 
-[Full Changelog](https://github.com/st0012/tapping_device/compare/v0.5.2...HEAD)
+[Full Changelog](https://github.com/st0012/tapping_device/compare/v0.5.7...HEAD)
+
+**Implemented enhancements:**
+
+- Support Ruby 3.0 [\#71](https://github.com/st0012/tapping_device/pull/71) ([st0012](https://github.com/st0012))
+
+**Merged pull requests:**
+
+- Drop activerecord requirement [\#73](https://github.com/st0012/tapping_device/pull/73) ([st0012](https://github.com/st0012))
+- Improve file-writing tests [\#72](https://github.com/st0012/tapping_device/pull/72) ([st0012](https://github.com/st0012))
+- Simplify output logic with Ruby' Logger class [\#70](https://github.com/st0012/tapping_device/pull/70) ([st0012](https://github.com/st0012))
+- Refactor Payload classes [\#68](https://github.com/st0012/tapping_device/pull/68) ([st0012](https://github.com/st0012))
+
+## [v0.5.7](https://github.com/st0012/tapping_device/tree/v0.5.7) (2020-09-09)
+
+[Full Changelog](https://github.com/st0012/tapping_device/compare/v0.5.6...v0.5.7)
+
+**Closed issues:**
+
+- Support tag option [\#64](https://github.com/st0012/tapping_device/issues/64)
+
+**Merged pull requests:**
+
+- Use pastel to replace handmade colorizing logic [\#66](https://github.com/st0012/tapping_device/pull/66) ([st0012](https://github.com/st0012))
+- Add tag option [\#65](https://github.com/st0012/tapping_device/pull/65) ([st0012](https://github.com/st0012))
+
+## [v0.5.6](https://github.com/st0012/tapping_device/tree/v0.5.6) (2020-07-17)
+
+[Full Changelog](https://github.com/st0012/tapping_device/compare/v0.5.5...v0.5.6)
+
+## [v0.5.5](https://github.com/st0012/tapping_device/tree/v0.5.5) (2020-07-16)
+
+[Full Changelog](https://github.com/st0012/tapping_device/compare/v0.5.4...v0.5.5)
+
+**Fixed bugs:**
+
+- InitializationTracker's logic can cause error [\#60](https://github.com/st0012/tapping_device/issues/60)
+
+**Closed issues:**
+
+- Refactor get\_method\_from\_object [\#59](https://github.com/st0012/tapping_device/issues/59)
+
+**Merged pull requests:**
+
+- Fix init tracker [\#61](https://github.com/st0012/tapping_device/pull/61) ([st0012](https://github.com/st0012))
+
+## [v0.5.4](https://github.com/st0012/tapping_device/tree/v0.5.4) (2020-07-05)
+
+[Full Changelog](https://github.com/st0012/tapping_device/compare/v0.5.3...v0.5.4)
+
+**Closed issues:**
+
+- Add with\_print\_calls method [\#52](https://github.com/st0012/tapping_device/issues/52)
+- Tapping any instance of class [\#51](https://github.com/st0012/tapping_device/issues/51)
+- Add ignore\_private option [\#50](https://github.com/st0012/tapping_device/issues/50)
+
+**Merged pull requests:**
+
+- Restructure README.md [\#58](https://github.com/st0012/tapping_device/pull/58) ([st0012](https://github.com/st0012))
+- Better support on private methods [\#57](https://github.com/st0012/tapping_device/pull/57) ([st0012](https://github.com/st0012))
+- Add with\_\* helpers \(e.g. with\_print\_calls\) [\#56](https://github.com/st0012/tapping_device/pull/56) ([st0012](https://github.com/st0012))
+- Add force\_recording option for debugging [\#55](https://github.com/st0012/tapping_device/pull/55) ([st0012](https://github.com/st0012))
+- Add print\_instance\_\* and write\_instance\_\* helpers [\#54](https://github.com/st0012/tapping_device/pull/54) ([st0012](https://github.com/st0012))
+- Fix tap\_init by adding c\_\* event type [\#53](https://github.com/st0012/tapping_device/pull/53) ([st0012](https://github.com/st0012))
+
+## [v0.5.3](https://github.com/st0012/tapping_device/tree/v0.5.3) (2020-06-21)
+
+[Full Changelog](https://github.com/st0012/tapping_device/compare/v0.5.2...v0.5.3)
 
 **Closed issues:**
 
+- Global Configuration [\#46](https://github.com/st0012/tapping_device/issues/46)
 - Support write\_\* helpers [\#44](https://github.com/st0012/tapping_device/issues/44)
 - Use Method\#source to replace Payload\#method\_head’s implementation  [\#19](https://github.com/st0012/tapping_device/issues/19)
 
 **Merged pull requests:**
 
+- Support Global Configuration [\#48](https://github.com/st0012/tapping_device/pull/48) ([st0012](https://github.com/st0012))
 - Support write\_\* helpers [\#47](https://github.com/st0012/tapping_device/pull/47) ([st0012](https://github.com/st0012))
 - Hijack attr methods with `hijack\_attr\_methods` option [\#45](https://github.com/st0012/tapping_device/pull/45) ([st0012](https://github.com/st0012))
 

data/Gemfile

@@ -2,3 +2,14 @@ source "https://rubygems.org"
 
 # Specify your gem's dependencies in tapping_device.gemspec
 gemspec
+
+rails_version = ENV["RAILS_VERSION"]
+rails_version = "6.1.0" if rails_version.nil?
+
+if rails_version.to_f < 6
+  gem "sqlite3", "~> 1.3.0"
+else
+  gem "sqlite3"
+end
+
+gem "activerecord", "~> #{rails_version}"

data/Makefile

@@ -0,0 +1,3 @@
+test:
+	bundle exec rspec
+	WITH_ACTIVE_RECORD=true bundle exec rspec spec/active_record_spec.rb

data/README.md

@@ -8,187 +8,119 @@
 
 
 ## Introduction
-`TappingDevice` makes the objects tell you what they do, so you don't need to track them yourself.
+As the name states, `TappingDevice` allows you to secretly listen to different events of an object:
 
-#### Contact Tracing For Objects
+- `Method Calls` - what does the object do
+- `Traces` - how is the object used by the application
+- `State Mutations` - what happens inside the object
 
-The concept is very simple. It's basically like [contact tracing](https://en.wikipedia.org/wiki/Contact_tracing) for your Ruby objects. You can use 
+After collecting the events, `TappingDevice` will output them in a nice, readable format to either stdout or a file. 
 
-- `print_calls(object)` to see what the object does
-- `print_traces(object)` to see how the object interacts with other objects (like used as an argument)
-- `print_mutations(object)` to see what actions changed the object's state (instance variables)
+**Ultimately, its goal is to let you know all the information you need for debugging with just 1 line of code.**
 
-Still sounds vague? Let's see some examples:
+## Usages
 
-### `print_calls` - Track Method Calls
+### Track Method Calls
 
-In [Discourse](https://github.com/discourse/discourse), it uses the `Guardian` class for authorization (like policy objects). It's barely visible in controller actions, but it does many checks under the hood. Now, let's say we want to know what the `Guardian` would do when a user creates a post; here's the controller action:
-
-```ruby
-  def create
-    @manager_params = create_params
-    @manager_params[:first_post_checks] = !is_api?
-
-    manager = NewPostManager.new(current_user, @manager_params)
-
-    if is_api?
-      memoized_payload = DistributedMemoizer.memoize(signature_for(@manager_params), 120) do
-        result = manager.perform
-        MultiJson.dump(serialize_data(result, NewPostResultSerializer, root: false))
-      end
-
-      parsed_payload = JSON.parse(memoized_payload)
-      backwards_compatible_json(parsed_payload, parsed_payload['success'])
-    else
-      result = manager.perform
-      json = serialize_data(result, NewPostResultSerializer, root: false)
-      backwards_compatible_json(json, result.success?)
-    end
-  end
-```
-
-As you can see, it doesn't even exist in the controller action, which makes tracking it by reading code very hard to do.
-
-But with `TappingDevice`. You can use `print_calls` to show what method calls the object performs
-
-```ruby
-  def create
-    # you can retrieve the current guardian object by calling guardian in the controller
-    print_calls(guardian)
-    @manager_params = create_params
-   
-    # .....
-```
-
-Now, if you execute the code, like via tests:
-
-```shell
-$ rspec spec/requests/posts_controller_spec.rb:603
-```
-
-You can get all the method calls it performs with basically everything you need to know
+By tracking an object's method calls, you'll be able to observe the object's behavior very easily
 
 <img src="https://github.com/st0012/tapping_device/blob/master/images/print_calls.png" alt="image of print_calls output" width="50%">
 
-Let's take a closer look at each entry. Everyone of them contains the method call's
-- method name 
-- method source class/module
+Each entry consists of 5 pieces of information:
+- method name
+- source of the method
 - call site
 - arguments
 - return value
 
 ![explanation of individual entry](https://github.com/st0012/tapping_device/blob/master/images/print_calls%20-%20single%20entry.png)
 
-These are the information you'd have to look up one by one manually (probably with many debug code writing). Now you can get all of them in just one line of code.
+#### Helpers
 
+- `print_calls(object)` - prints the result to stdout
+- `write_calls(object, log_file: "file_name")` - writes the result to a file
+	- the default file is `/tmp/tapping_device.log`, but you can change it with `log_file: "new_path"` option
 
-### `print_traces` - See The Object's Traces
+#### Use Cases
+- Understand a service object/form object's behavior
+- Debug a messy controller
 
-If you're not interested in what an object does, but what it interacts with other parts of the program, e.g., used as arguments. You can use the `print_traces` helper. Let's see how `Discourse` uses the `manager` object when creating a post
+### Track Traces
 
-```ruby
-  def create
-    @manager_params = create_params
-    @manager_params[:first_post_checks] = !is_api?
-   
-    manager = NewPostManager.new(current_user, @manager_params)
-
-    print_traces(manager)
-    # .....
-```
+By tracking an object's traces, you'll be able to observe the object's journey in your application
 
-And after running the test case
+![image of print_traces output](https://github.com/st0012/tapping_device/blob/master/images/print_traces.png)
 
-```shell
-$ rspec spec/requests/posts_controller_spec.rb:603
-```
+#### Helpers
 
-You will see that it performs 2 calls: `perform` and `perform_create_post`. And it's also used as `manager` argument in various of calls of the `NewPostManager` class.
+- `print_traces(object)` - prints the result to stdout
+- `write_traces(object, log_file: "file_name")` - writes the result to a file
+	- the default file is `/tmp/tapping_device.log`, but you can change it with `log_file: "new_path"` option
 
-![image of print_traces output](https://github.com/st0012/tapping_device/blob/master/images/print_traces.png)
+#### Use Cases
+- Debug argument related issues
+- Understand how a library uses your objects
 
-### `print_mutations` - Display All State Changes At Once
+### Track State Mutations
 
-Another thing that often bothers developers in debugging is to track an object's internal state changes. And `tapping_device` allows you to see all state changes with just one line of code. Let me keep using [Discourse](https://github.com/discourse/discourse) to demonstrate it. 
+By tracking an object's traces, you'll be able to observe the state changes happen inside the object between each method call
 
-When updating a post, it uses an object called `PostRevisor` to revise it:
+<img src="https://github.com/st0012/tapping_device/blob/master/images/print_mutations.png" alt="image of print_mutations output" width="50%">
 
-```ruby
-# app/controllers/posts_controller.rb
-class PostsController
-  def update
-    # ......
-    revisor = PostRevisor.new(post, topic)
-    revisor.revise!(current_user, changes, opts)
-    # ......
-  end
-end
-```
+#### Helpers
 
-In the `PostReviser#revise!`, it uses many instance variables to track different information:
+- `print_mutations(object)` - prints the result to stdout
+- `write_mutations(object, log_file: "file_name")` - writes the result to a file
+	- the default file is `/tmp/tapping_device.log`, but you can change it with `log_file: "new_path"` option
 
-```ruby
-  # lib/post_revisor.rb
-  def revise!(editor, fields, opts = {})
-    @editor = editor
-    @fields = fields.with_indifferent_access
-    @opts = opts
+#### Use Cases
+- Debug state related issues
+- Debug memoization issues
 
-    @topic_changes = TopicChanges.new(@topic, editor)
-    
-    # ......
+### Track All Instances Of A Class
 
-    @revised_at = @opts[:revised_at] || Time.now
-    @last_version_at = @post.last_version_at || Time.now
+It's not always easy to directly access the objects we want to track, especially when they're managed by a library (e.g. `ActiveRecord::Relation`). In such cases, you can use these helpers to track the class's instances:
 
-    @version_changed = false
-    @post_successfully_saved = true
+- `print_instance_calls(ObjectKlass)`
+- `print_instance_traces(ObjectKlass)`
+- `print_instance_mutations(ObjectKlass)`
+- `write_instance_calls(ObjectKlass)`
+- `write_instance_traces(ObjectKlass)`
+- `write_instance_mutations(ObjectKlass)`
 
-    @validate_post = true
-    # ......
-  end
-```
 
-Tracking the changes of that many instance variables can be a painful task, especially when we want to know the values before and after certain method call. This is why I created `print_mutations` to save us from this. 
+### Use `with_HELPER_NAME` for chained method calls
 
-Like other helpers, you only need 1 line of code
+In Ruby programs, we often chain multiple methods together like this:
 
 ```ruby
-# app/controllers/posts_controller.rb
-class PostsController
-  def update
-    # ......
-    revisor = PostRevisor.new(post, topic)
-    print_mutations(revisor)
-    revisor.revise!(current_user, changes, opts)
-    # ......
-  end
-end
+SomeService.new(params).perform
 ```
 
-And then you'll see all the state changes:
+And to debug it, we'll need to break the method chain into
 
-<img src="https://github.com/st0012/tapping_device/blob/master/images/print_mutations.png" alt="image of print_mutations output" width="50%">
-
-Now you can see what method changes which states. And more importantly, you get to see all the sate changes at once!
-
-**You can try these examples on [my fork of discourse](https://github.com/st0012/discourse/tree/demo-for-tapping-device)**
+```ruby
+service = SomeService.new(params)
+print_calls(service, options)
+service.perform
+```
 
-### `write_*` helpers
+This kind of code changes are usually annoying, and that's one of the problems I want to solve with `TappingDevice`.
 
-`tapping_device` also provides helpers that write the events into files:
+So here's another option, just insert a `with_HELPER_NAME` call in between:
 
-- `write_calls(object)`
-- `write_traces(object)`
-- `write_mutations(object)`
+```ruby
+SomeService.new(params).with_print_calls(options).perform
+```
 
-The default destination is `/tmp/tapping_device.log`. You can change it with the `log_file`  option:
+And it'll behave exactly like
 
 ```ruby
-write_calls(object, log_file: "/tmp/another_file")
+service = SomeService.new(params)
+print_calls(service, options)
+service.perform
 ```
 
-
 ## Installation
 Add this line to your application's Gemfile:
 
@@ -296,6 +228,40 @@ The default is `false` because
 2. It's still unclear if this hack safe enough for most applications.
 
 
+#### `ignore_private`
+
+Sometimes we use many private methods to perform trivial operations, like
+
+```ruby
+class Operation
+  def extras
+    dig_attribute("extras")
+  end
+
+  private
+
+  def data
+    @data
+  end
+
+  def dig_attribute(attr)
+    data.dig("attributes", attr) 
+  end
+end
+```
+
+And we may not be interested in those method calls. If that's the case, you can use the `ignore_private` option
+
+```ruby
+operation = Operation.new(params)
+print_calls(operation, ignore_private: true) #=> only prints the `extras` call
+```
+
+#### `only_private`
+
+This option does the opposite of the `ignore_private` option does.
+
+
 ### Global Configuration
 
 If you don't want to pass options every time you use a helper, you can use global configuration to change the default values:
@@ -341,3 +307,4 @@ The gem is available as open-source under the terms of the [MIT License](https:/
 ## Code of Conduct
 
 Everyone interacting in the TappingDevice project's codebases, issue trackers, chat rooms, and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/tapping_device/blob/master/CODE_OF_CONDUCT.md).
+

data/lib/tapping_device.rb

@@ -1,4 +1,3 @@
-require "active_record"
 require "active_support/core_ext/module/introspection"
 require "pry" # for using Method#source
 
@@ -34,7 +33,7 @@ class TappingDevice
   def initialize(options = {}, &block)
     @block = block
     @output_block = nil
-    @options = process_options(options)
+    @options = process_options(options.dup)
     @calls = []
     @disabled = false
     @with_condition = nil
@@ -94,15 +93,19 @@ class TappingDevice
   private
 
   def build_minimum_trace_point(event_type:)
-    TracePoint.new(event_type) do |tp|
+    TracePoint.new(*event_type) do |tp|
       next unless filter_condition_satisfied?(tp)
-      next if is_tapping_device_call?(tp)
 
       filepath, line_number = get_call_location(tp)
       payload = build_payload(tp: tp, filepath: filepath, line_number: line_number)
 
-      next if should_be_skipped_by_paths?(filepath)
-      next unless with_condition_satisfied?(payload)
+      unless @options[:force_recording]
+        next if is_tapping_device_call?(tp)
+        next if should_be_skipped_by_paths?(filepath)
+        next unless with_condition_satisfied?(payload)
+        next if payload.is_private_call? && @options[:ignore_private]
+        next if !payload.is_private_call? && @options[:only_private]
+      end
 
       yield(payload)
     end
@@ -137,7 +140,7 @@ class TappingDevice
   end
 
   def build_payload(tp:, filepath:, line_number:)
-    Payload.init({
+    Payload.new(
       target: @target,
       receiver: tp.self,
       method_name: tp.callee_id,
@@ -148,15 +151,14 @@ class TappingDevice
       line_number: line_number,
       defined_class: tp.defined_class,
       trace: get_traces(tp),
+      is_private_call: tp.defined_class.private_method_defined?(tp.callee_id),
+      tag: options[:tag],
       tp: tp
-    })
+    )
   end
 
   def get_method_object_from(target, method_name)
-    target.method(method_name)
-  rescue ArgumentError
-    method_method = Object.method(:method).unbind
-    method_method.bind(target).call(method_name)
+    Object.instance_method(:method).bind(target).call(method_name)
   rescue NameError
     # if any part of the program uses Refinement to extend its methods
     # we might still get NoMethodError when trying to get that method outside the scope
@@ -204,6 +206,10 @@ class TappingDevice
     options[:event_type] ||= config[:event_type]
     options[:hijack_attr_methods] ||= config[:hijack_attr_methods]
     options[:track_as_records] ||= config[:track_as_records]
+    options[:ignore_private] ||= config[:ignore_private]
+    options[:only_private] ||= config[:only_private]
+    # for debugging the gem more easily
+    options[:force_recording] ||= false
 
     options[:descendants] ||= []
     options[:root_device] ||= self

data/lib/tapping_device/configurable.rb

@@ -12,6 +12,8 @@ class TappingDevice
       event_type: :return,
       hijack_attr_methods: false,
       track_as_records: false,
+      ignore_private: false,
+      only_private: false
     }.merge(TappingDevice::Output::DEFAULT_OPTIONS)
 
     included do

data/lib/tapping_device/method_hijacker.rb

@@ -20,10 +20,14 @@ class TappingDevice
 
     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)

data/lib/tapping_device/output.rb

@@ -1,7 +1,6 @@
-require "tapping_device/output/payload"
+require "logger"
+require "tapping_device/output/payload_wrapper"
 require "tapping_device/output/writer"
-require "tapping_device/output/stdout_writer"
-require "tapping_device/output/file_writer"
 
 class TappingDevice
   module Output
@@ -13,16 +12,16 @@ class TappingDevice
 
     module Helpers
       def and_write(payload_method = nil, options: {}, &block)
-        and_output(payload_method, options: options, writer_klass: FileWriter, &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, writer_klass: StdoutWriter, &block)
+        and_output(payload_method, options: options, logger: Logger.new($stdout), &block)
       end
 
-      def and_output(payload_method = nil, options: {}, writer_klass:, &block)
+      def and_output(payload_method = nil, options: {}, logger:, &block)
         output_block = generate_output_block(payload_method, block)
-        @output_writer = writer_klass.new(options, output_block)
+        @output_writer = Writer.new(options: options, output_block: output_block, logger: logger)
         self
       end
 

data/lib/tapping_device/output/{payload.rb → payload_wrapper.rb}

@@ -1,13 +1,44 @@
+require "pastel"
+
 class TappingDevice
   module Output
-    class Payload < Payload
+    class PayloadWrapper
       UNDEFINED = "[undefined]"
+      PRIVATE_MARK = " (private)"
+
+      PASTEL = Pastel.new
+      PASTEL.alias_color(:orange, :bright_red, :bright_yellow)
+
+      TappingDevice::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 = {})
-        ":#{super(options)}"
+        name = ":#{@payload.method_name}"
+
+        name += " [#{tag}]" if tag
+        name += PRIVATE_MARK if is_private_call?
+
+        name
       end
 
       def arguments(options = {})
@@ -18,29 +49,13 @@ class TappingDevice
         generate_string_result(raw_return_value, options[:inspect])
       end
 
-      COLOR_CODES = {
-        green: 10,
-        yellow: 11,
-        blue: 12,
-        megenta: 13,
-        cyan: 14,
-        orange: 214
-      }
-
-      COLORS = COLOR_CODES.each_with_object({}) do |(name, code), hash|
-        hash[name] = "\u001b[38;5;#{code}m"
-      end.merge(
-        reset: "\u001b[0m",
-        nocolor: ""
-      )
-
       PAYLOAD_ATTRIBUTES = {
-        method_name: {symbol: "", color: COLORS[:blue]},
-        location: {symbol: "from:", color: COLORS[:green]},
-        return_value: {symbol: "=>", color: COLORS[:megenta]},
-        arguments: {symbol: "<=", color: COLORS[:orange]},
-        ivar_changes: {symbol: "changes:\n", color: COLORS[:blue]},
-        defined_class: {symbol: "#", color: COLORS[:yellow]}
+        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|
@@ -53,7 +68,7 @@ class TappingDevice
           call_result = send("original_#{attribute}", options)
 
           if options[:colorize]
-            "#{color}#{call_result}#{COLORS[:reset]}"
+            PASTEL.send(color, call_result)
           else
             call_result
           end
@@ -83,7 +98,7 @@ class TappingDevice
         return unless arg_name
 
         arg_name = ":#{arg_name}"
-        arg_name = value_with_color(arg_name, :orange) if options[:colorize]
+        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
@@ -100,17 +115,17 @@ class TappingDevice
       end
 
       def ivar_changes(options = {})
-        super.map do |ivar, value_changes|
+        @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 = "#{COLORS[:orange]}#{ivar}#{COLORS[:reset]}"
-            before = "#{COLORS[:blue]}#{before.to_s}#{COLORS[:reset]}"
-            after = "#{COLORS[:blue]}#{after.to_s}#{COLORS[:reset]}"
+            ivar = PASTEL.orange(ivar)
+            before = PASTEL.bright_blue(before.to_s)
+            after = PASTEL.bright_blue(after.to_s)
           end
 
-          "      #{ivar}: #{before.to_s} => #{after.to_s}"
+          "      #{ivar}: #{before} => #{after}"
         end.join("\n")
       end
 
@@ -126,10 +141,6 @@ class TappingDevice
 
       private
 
-      def value_with_color(value, color)
-        "#{COLORS[color]}#{value}#{COLORS[:reset]}"
-      end
-
       def generate_string_result(obj, inspect)
         case obj
         when Array

data/lib/tapping_device/output/writer.rb

@@ -1,19 +1,21 @@
 class TappingDevice
   module Output
     class Writer
-      def initialize(options, output_block)
+      def initialize(options:, output_block:, logger:)
         @options = options
         @output_block = output_block
+        @logger = logger
       end
 
       def write!(payload)
-        raise NotImplementedError
+        output = generate_output(payload)
+        @logger << output
       end
 
       private
 
       def generate_output(payload)
-        @output_block.call(Output::Payload.init(payload), @options)
+        @output_block.call(PayloadWrapper.new(payload), @options)
       end
     end
   end

data/lib/tapping_device/payload.rb

@@ -1,22 +1,32 @@
 class TappingDevice
-  class Payload < Hash
+  class Payload
     ATTRS = [
       :target, :receiver, :method_name, :method_object, :arguments, :return_value, :filepath, :line_number,
-      :defined_class, :trace, :tp, :ivar_changes
+      :defined_class, :trace, :tag, :tp, :ivar_changes, :is_private_call
     ]
 
-    ATTRS.each do |attr|
-      define_method attr do |options = {}|
-        self[attr]
-      end
-    end
+    attr_accessor(*ATTRS)
+
+    alias :is_private_call? :is_private_call
 
-    def self.init(hash)
-      h = new
-      hash.each do |k, v|
-        h[k] = v
-      end
-      h
+    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

data/lib/tapping_device/trackable.rb

@@ -20,28 +20,29 @@ class TappingDevice
       TappingDevice::Trackers::MutationTracker.new(options, &block).track(object)
     end
 
-    def print_traces(target, options = {})
-      output_traces(target, options, output_action: :and_print)
-    end
+    [:calls, :traces, :mutations].each do |subject|
+      [:print, :write].each do |output_action|
+        helper_method_name = "#{output_action}_#{subject}"
 
-    def write_traces(target, options = {})
-      output_traces(target, options, output_action: :and_write)
-    end
+        define_method helper_method_name do |target, options = {}|
+          send("output_#{subject}", target, options, output_action: "and_#{output_action}")
+        end
 
-    def print_calls(target, options = {})
-      output_calls(target, options, output_action: :and_print)
-    end
+        define_method "with_#{helper_method_name}" do |options = {}|
+          send(helper_method_name, self, options)
+          self
+        end
 
-    def write_calls(target, options = {})
-      output_calls(target, options, output_action: :and_write)
-    end
+        define_method "#{output_action}_instance_#{subject}" do |target_klass, options = {}|
+          collection_proxy = AsyncCollectionProxy.new
 
-    def print_mutations(target, options = {})
-      output_mutations(target, options, output_action: :and_print)
-    end
+          tap_init!(target_klass, options.merge(force_recording: true)) do |payload|
+            collection_proxy << send(helper_method_name, payload.return_value, options)
+          end
 
-    def write_mutations(target, options = {})
-      output_mutations(target, options, output_action: :and_write)
+          collection_proxy
+        end
+      end
     end
 
     private
@@ -84,12 +85,15 @@ class TappingDevice
       [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
 
-      [:stop!, :stop_when, :with].each do |method|
+      CHAINABLE_ACTIONS.each do |method|
         define_method method do |&block|
           @devices.each do |device|
             device.send(method, &block)
@@ -97,6 +101,32 @@ class TappingDevice
         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
 

data/lib/tapping_device/trackers/initialization_tracker.rb

@@ -1,10 +1,27 @@
 class TappingDevice
   module Trackers
     class InitializationTracker < TappingDevice
+      def initialize(options = {}, &block)
+        super
+        event_type = @options[:event_type]
+        # if a class doesn't override the 'initialize' method
+        # Class.new will only trigger c_return or c_call
+        @options[:event_type] = [event_type, "c_#{event_type}"]
+      end
+
+      def track(object)
+        super
+        @is_active_record_model = defined?(ActiveRecord) && target.ancestors.include?(ActiveRecord::Base)
+        self
+      end
+
       def build_payload(tp:, filepath:, line_number:)
         payload = super
-        payload[:return_value] = payload[:receiver]
-        payload[:receiver] = target
+
+        return payload if @is_active_record_model
+
+        payload.return_value = payload.receiver
+        payload.receiver = target
         payload
       end
 
@@ -16,8 +33,17 @@ class TappingDevice
         receiver = tp.self
         method_name = tp.callee_id
 
-        if target.ancestors.include?(ActiveRecord::Base)
-          method_name == :new && receiver.ancestors.include?(target)
+        if @is_active_record_model
+          # ActiveRecord redefines model classes' .new method,
+          # so instead of calling Model#initialize, it'll actually call Model.new
+          # see https://github.com/rails/rails/blob/master/activerecord/lib/active_record/inheritance.rb#L50
+          method_name == :new &&
+            receiver.is_a?(Class) &&
+            # this checks if the model class is the target class or a subclass of it
+            receiver.ancestors.include?(target) &&
+            # Model.new triggers both c_return and return events. so we should only return in 1 type of the events
+            # otherwise the callback will be triggered twice
+            tp.event == :return
         else
           method_name == :initialize && receiver.is_a?(target)
         end

data/lib/tapping_device/trackers/mutation_tracker.rb

@@ -47,7 +47,7 @@ class TappingDevice
         payload = super
 
         if change_capturing_event?(tp)
-          payload[:ivar_changes] = capture_ivar_changes
+          payload.ivar_changes = capture_ivar_changes
         end
 
         payload
@@ -55,15 +55,14 @@ class TappingDevice
 
       def capture_ivar_changes
         changes = {}
-
         additional_keys = @latest_instance_variables.keys - @instance_variables_snapshot.keys
         additional_keys.each do |key|
-          changes[key] = {before: Output::Payload::UNDEFINED, after: @latest_instance_variables[key]}
+          changes[key] = {before: Output::PayloadWrapper::UNDEFINED, after: @latest_instance_variables[key]}
         end
 
         removed_keys = @instance_variables_snapshot.keys - @latest_instance_variables.keys
         removed_keys.each do |key|
-          changes[key] = {before: @instance_variables_snapshot[key], after: Output::Payload::UNDEFINED}
+          changes[key] = {before: @instance_variables_snapshot[key], after: Output::PayloadWrapper::UNDEFINED}
         end
 
         remained_keys = @latest_instance_variables.keys - additional_keys

data/lib/tapping_device/version.rb

@@ -1,3 +1,3 @@
 class TappingDevice
-  VERSION = "0.5.3"
+  VERSION = "0.6.0"
 end

data/tapping_device.gemspec

@@ -26,16 +26,10 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  if ENV["RAILS_VERSION"]
-    spec.add_dependency "activerecord", "~> #{ENV["RAILS_VERSION"]}"
-  else
-    spec.add_dependency "activerecord", ">= 5.2"
-  end
-
   spec.add_dependency "pry" # for using Method#source in MutationTracker
   spec.add_dependency "activesupport"
+  spec.add_dependency "pastel"
 
-  spec.add_development_dependency "sqlite3", ">= 1.3.6"
   spec.add_development_dependency "database_cleaner"
   spec.add_development_dependency "bundler", "~> 2.0"
   spec.add_development_dependency "rake", "~> 13.0"

metadata

@@ -1,29 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: tapping_device
 version: !ruby/object:Gem::Version
-  version: 0.5.3
+  version: 0.6.0
 platform: ruby
 authors:
 - st0012
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2020-06-21 00:00:00.000000000 Z
+date: 2021-04-25 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: activerecord
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '5.2'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '5.2'
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
@@ -53,19 +39,19 @@ dependencies:
       - !ruby/object:Gem::Version
         version: '0'
 - !ruby/object:Gem::Dependency
-  name: sqlite3
+  name: pastel
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.3.6
-  type: :development
+        version: '0'
+  type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - ">="
       - !ruby/object:Gem::Version
-        version: 1.3.6
+        version: '0'
 - !ruby/object:Gem::Dependency
   name: database_cleaner
   requirement: !ruby/object:Gem::Requirement
@@ -154,8 +140,8 @@ files:
 - CHANGELOG.md
 - CODE_OF_CONDUCT.md
 - Gemfile
-- Gemfile.lock
 - LICENSE.txt
+- Makefile
 - README.md
 - Rakefile
 - bin/console
@@ -170,9 +156,7 @@ files:
 - lib/tapping_device/manageable.rb
 - lib/tapping_device/method_hijacker.rb
 - lib/tapping_device/output.rb
-- lib/tapping_device/output/file_writer.rb
-- lib/tapping_device/output/payload.rb
-- lib/tapping_device/output/stdout_writer.rb
+- lib/tapping_device/output/payload_wrapper.rb
 - lib/tapping_device/output/writer.rb
 - lib/tapping_device/payload.rb
 - lib/tapping_device/trackable.rb
@@ -205,7 +189,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.0.3
+rubygems_version: 3.2.15
 signing_key: 
 specification_version: 4
 summary: tapping_device lets you understand what your Ruby objects do without digging

data/Gemfile.lock

@@ -1,74 +0,0 @@
-PATH
-  remote: .
-  specs:
-    tapping_device (0.5.3)
-      activerecord (>= 5.2)
-      activesupport
-      pry
-
-GEM
-  remote: https://rubygems.org/
-  specs:
-    activemodel (6.0.3.2)
-      activesupport (= 6.0.3.2)
-    activerecord (6.0.3.2)
-      activemodel (= 6.0.3.2)
-      activesupport (= 6.0.3.2)
-    activesupport (6.0.3.2)
-      concurrent-ruby (~> 1.0, >= 1.0.2)
-      i18n (>= 0.7, < 2)
-      minitest (~> 5.1)
-      tzinfo (~> 1.1)
-      zeitwerk (~> 2.2, >= 2.2.2)
-    coderay (1.1.3)
-    concurrent-ruby (1.1.6)
-    database_cleaner (1.7.0)
-    diff-lcs (1.3)
-    docile (1.3.2)
-    i18n (1.8.3)
-      concurrent-ruby (~> 1.0)
-    json (2.3.0)
-    method_source (1.0.0)
-    minitest (5.14.1)
-    pry (0.13.1)
-      coderay (~> 1.1)
-      method_source (~> 1.0)
-    rake (13.0.1)
-    rspec (3.8.0)
-      rspec-core (~> 3.8.0)
-      rspec-expectations (~> 3.8.0)
-      rspec-mocks (~> 3.8.0)
-    rspec-core (3.8.2)
-      rspec-support (~> 3.8.0)
-    rspec-expectations (3.8.4)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.8.0)
-    rspec-mocks (3.8.1)
-      diff-lcs (>= 1.2.0, < 2.0)
-      rspec-support (~> 3.8.0)
-    rspec-support (3.8.2)
-    simplecov (0.17.1)
-      docile (~> 1.1)
-      json (>= 1.8, < 3)
-      simplecov-html (~> 0.10.0)
-    simplecov-html (0.10.2)
-    sqlite3 (1.4.1)
-    thread_safe (0.3.6)
-    tzinfo (1.2.7)
-      thread_safe (~> 0.1)
-    zeitwerk (2.3.0)
-
-PLATFORMS
-  ruby
-
-DEPENDENCIES
-  bundler (~> 2.0)
-  database_cleaner
-  rake (~> 13.0)
-  rspec (~> 3.0)
-  simplecov (= 0.17.1)
-  sqlite3 (>= 1.3.6)
-  tapping_device!
-
-BUNDLED WITH
-   2.1.1

data/lib/tapping_device/output/file_writer.rb

@@ -1,21 +0,0 @@
-class TappingDevice
-  module Output
-    class FileWriter < Writer
-      def initialize(options, output_block)
-        @path = options[:log_file]
-
-        File.write(@path, "") # clean file
-
-        super
-      end
-
-      def write!(payload)
-        output = generate_output(payload)
-
-        File.open(@path, "a") do |f|
-          f << output
-        end
-      end
-    end
-  end
-end

data/lib/tapping_device/output/stdout_writer.rb

@@ -1,9 +0,0 @@
-class TappingDevice
-  module Output
-    class StdoutWriter < Writer
-      def write!(payload)
-        puts(generate_output(payload))
-      end
-    end
-  end
-end