columns_trace 0.1.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cd2b5b47e4fa2ca409bf7dd531c8766a6ff6487b50e996f04425577c07a65667
-  data.tar.gz: 28fa32928a82d9c1df876bad8002d677bd7c7e5f0a001f56ad6170b9b87e8f2c
+  metadata.gz: 9b9167813d7f9a2089f1eb2380bc62de8289384ed56f33fc4983ca716b76c0a9
+  data.tar.gz: 0ce77996e83a1af64bb9d64acc7231965e1a46263b9be30bb870a3e3a0a6a140
 SHA512:
-  metadata.gz: df2740562388acd113084e28f50940d2bbf0d0d934abe0b8b4def515158f2bb36ba29179ae317e7cf77665039e5d77d2c15d76ef044b3e4f56f314f046882ba0
-  data.tar.gz: 77fcfa0230679ba9efc329225c6eda32f6ad915bc0bee79df227b724bc1c75ba3cb5e7b51943b1142ba36586f74d94cdeec9bc9873daa807f1e009c4c53f8e4f
+  metadata.gz: a2f63e4cc55f26f7f86670c65378f203e8ea4e703ccd8079e5a4c201729eddb2de42277f654108ef80b61dc29c31ba5211a97fec44f05076480234e65a3221b5
+  data.tar.gz: 3fbddc61ae15705ecb191b3d1856f726b292c59d6973b80c4f464555765e423551572fea0e17a21e3019839b9b109e1f0803fc86db588ab9ac3752da8f3d6a3b

data/CHANGELOG.md

@@ -1,3 +1,32 @@
 ## master (unreleased)
 
+## 0.3.0 (2023-11-09)
+
+  - Add ability to trace columns usage in custom code
+  - Trace unused columns in mailers
+
+## 0.2.0 (2023-10-13)
+
+- Allow to use custom reporters
+
+  ```ruby
+  class MyReporter
+    def report(title, created_records)
+      # do actual reporting
+    end
+  end
+
+  ColumnsTrace.reporter = MyReporter.new
+  ```
+
+  `ColumnsTrace.logger=` setting is removed in favor of using `ColumnsTrace.reporter=`.
+  If you configured custom logger, you should now configure it via:
+
+  ```ruby
+  logger = ActiveSupport::Logger.new("/my/custom/logger.log")
+  ColumnsTrace.reporter = ColumnsTrace::LogReporter.new(logger)
+  ```
+
+## 0.1.0 (2023-10-04)
+
 - First release

data/README.md

@@ -25,7 +25,7 @@ $ bundle install
 
 ## Usage
 
-Hit a controller action or run `ActiveJob` (or `Sidekiq`) job, open `log/columns_trace.log`,
+Hit a controller or email action or run `ActiveJob` (or `Sidekiq`) job, open `log/columns_trace.log`,
 and see the output:
 
 ```
@@ -54,6 +54,18 @@ ImportProjectJob
   ↳ app/jobs/import_project_job.rb:24:in `perform'
 ```
 
+### Tracing custom code
+
+To get columns usage in the custom code, you can manually wrap it by `ColumnsTrace.report`:
+
+```ruby
+task my_rake_task: :environment do
+  ColumnsTrace.report("my_rake_task") do
+    # do stuff
+  end
+end
+```
+
 ## Configuration
 
 You can override the following default options:
@@ -75,10 +87,10 @@ ColumnsTrace.configure do |config|
   #   config.ignored_columns = [:updated_at, { User => :admin }]
   config.ignored_columns = []
 
-  # The logger to log to.
-  # Defaults to logger, that outputs to `log/columns_trace.log` file
-  # when the gem is used in the Rails app.
-  config.logger = nil
+  # The reporter that is used for reporting.
+  # Defaults to log reporter that outputs to `log/columns_trace.log` file
+  # when inside a Rails application.
+  config.reporter = nil
 
   # Controls the contents of the printed backtrace.
   # Is set to the default Rails.backtrace_cleaner when the gem is used in the Rails app.
@@ -94,6 +106,31 @@ end
 ColumnsTrace.enable_sidekiq_tracing!
 ```
 
+### Custom reporters
+
+By default offenses are reported to a log reporter that outputs to `log/columns_trace.log` file
+when inside a Rails application.
+
+You can set your custom reporter by defining a class responding to `#report` method.
+
+```ruby
+class MyReporter
+  def report(title, created_records)
+    title # => "controller#action"
+    created_records # => [#<ColumnsTrace::CreatedRecord>]
+    created_records.each do |record|
+      record.model # class of ActiveRecord model
+      record.accessed_fields  # array of accessed fields
+      record.unused_fields # array of unused fields
+      record.backtrace # array of strings
+      record.record # ActiveRecord model instance
+    end
+  end
+end
+
+ColumnsTrace.reporter = MyReporter.new
+```
+
 ## Development
 
 After checking out the repo, run `bundle install` to install dependencies. Then, run `rake` to run the linter and tests.

data/lib/columns_trace/created_record.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module ColumnsTrace
+  # Class that is used to store metadata about created ActiveRecord records.
+  class CreatedRecord
+    # Model class
+    # @return [Class]
+    #
+    attr_reader :model
+
+    # Model instance
+    # @return [ActiveRecord::Base]
+    #
+    attr_reader :record
+
+    # Backtrace where the instance was created
+    # @return [Array<String>]
+    #
+    attr_reader :backtrace
+
+    def initialize(record, backtrace)
+      @model = record.class
+      @record = record
+      @backtrace = backtrace
+    end
+
+    # Get accessed fields on model instance
+    # @return [Array<String>]
+    #
+    def accessed_fields
+      @accessed_fields ||= record.accessed_fields
+    end
+
+    # Get unused fields on model instance
+    # @return [Array<String>]
+    #
+    def unused_fields
+      # We need to store this into local variable, because `record.attributes`
+      # will access all attributes.
+      accessed = accessed_fields
+      record.attributes.keys - accessed
+    end
+  end
+end

data/lib/columns_trace/log_reporter.rb

@@ -0,0 +1,57 @@
+# frozen_string_literal: true
+
+module ColumnsTrace
+  # Reporter that reports into the provided logger.
+  class LogReporter
+    def initialize(logger)
+      @logger = logger
+    end
+
+    # Main reporter's method
+    #
+    # @param title [String] title of the reporting, e.g. controller action etc
+    # @param created_records [Array<ColumnsTrace::CreatedRecord>] items that hold
+    #   metadata about created records
+    #
+    def report(title, created_records)
+      lines = []
+
+      created_records.group_by(&:model).each do |model, grouped_created_records|
+        lines.concat(lines_for_created_records(model, grouped_created_records))
+      end
+
+      if lines.any?
+        @logger.info("#{title}\n#{lines.join("\n")}")
+      end
+    end
+
+    private
+      def lines_for_created_records(model, created_records)
+        lines = []
+
+        created_records.group_by(&:backtrace).each do |backtrace, grouped_created_records|
+          accessed = accessed_fields(grouped_created_records)
+          unused = grouped_created_records.first.unused_fields - accessed
+          unused.reject! { |column| ColumnsTrace.ignored_column?(model, column) }
+
+          if unused.any?
+            records_text = "record".pluralize(grouped_created_records.size)
+            lines << <<-MSG
+  #{grouped_created_records.size} #{model.name} #{records_text}: unused columns - #{format_columns(unused)}; used columns - #{format_columns(accessed)}
+  ↳ #{backtrace.join("\n  ")}
+            MSG
+          end
+        end
+
+        lines
+      end
+
+      def accessed_fields(created_records)
+        created_records.map(&:accessed_fields).flatten.uniq
+      end
+
+      def format_columns(columns)
+        columns.map(&:inspect).join(", ")
+      end
+  end
+end

data/lib/columns_trace/rails_integration.rb

@@ -14,12 +14,20 @@ module ColumnsTrace
   end
 
   ActiveSupport.on_load(:action_controller) do
-    before_action { Registry.clear }
-    after_action { Reporter.report("#{self.class.name}##{action_name}") }
+    around_action do |controller, action|
+      ColumnsTrace.report("#{controller.class.name}##{action_name}", &action)
+    end
+  end
+
+  ActiveSupport.on_load(:action_mailer) do
+    around_action do |mailer, action|
+      ColumnsTrace.report("#{mailer.class.name}##{action_name}", &action)
+    end
   end
 
   ActiveSupport.on_load(:active_job) do
-    before_perform { Registry.clear }
-    after_perform { Reporter.report(self.class.name) }
+    around_perform do |job, perform|
+      ColumnsTrace.report("#{job.class.name}#perform", &perform)
+    end
   end
 end

data/lib/columns_trace/railtie.rb

@@ -5,7 +5,9 @@ module ColumnsTrace
   class Railtie < Rails::Railtie
     initializer "columns_trace.set_configs" do
       ColumnsTrace.backtrace_cleaner = Rails.backtrace_cleaner
-      ColumnsTrace.logger = ActiveSupport::Logger.new(Rails.root.join("log", "columns_trace.log"))
+
+      logger = ActiveSupport::Logger.new(Rails.root.join("log", "columns_trace.log"))
+      ColumnsTrace.reporter = LogReporter.new(logger)
     end
   end
 end

data/lib/columns_trace/registry.rb

@@ -4,18 +4,16 @@ module ColumnsTrace
   # @private
   # Note: can use ActiveSupport::IsolatedExecutionState instead of this module for rails 7.0+.
   module Registry
-    Entry = Struct.new(:model, :record, :backtrace)
-
     class << self
       def register(record, backtrace)
-        state << Entry.new(record.class, record, backtrace)
+        state << CreatedRecord.new(record, backtrace)
       end
 
       def clear
         state.clear
       end
 
-      def entries
+      def created_records
         state
       end
 

data/lib/columns_trace/sidekiq_integration.rb

@@ -3,10 +3,8 @@
 module ColumnsTrace
   # @private
   class SidekiqMiddleware
-    def call(worker, _job, _queue)
-      Registry.clear
-      yield
-      Reporter.report(worker.class.name)
+    def call(worker, _job, _queue, &block)
+      ColumnsTrace.report("#{worker.class.name}#perform", &block)
     end
   end
 end

data/lib/columns_trace/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module ColumnsTrace
-  VERSION = "0.1.0"
+  VERSION = "0.3.0"
 end

data/lib/columns_trace.rb

@@ -2,14 +2,32 @@
 
 require "active_record"
 
+require_relative "columns_trace/created_record"
 require_relative "columns_trace/registry"
 require_relative "columns_trace/rails_integration"
-require_relative "columns_trace/reporter"
+require_relative "columns_trace/log_reporter"
 require_relative "columns_trace/version"
 require_relative "columns_trace/railtie" if defined?(Rails)
 
 module ColumnsTrace
   class << self
+    # Manually trace columns usage in an arbitrary code.
+    #
+    # @param title [String] title of the reporting, e.g. controller action etc
+    #
+    # @example
+    #   task my_rake_task: :environment do
+    #     ColumnsTrace.report("my_rake_task") do
+    #       # do stuff
+    #     end
+    #   end
+    #
+    def report(title)
+      Registry.clear
+      yield
+      reporter.report(title, Registry.created_records)
+    end
+
     # @private
     attr_reader :ignored_models
 
@@ -54,11 +72,11 @@ module ColumnsTrace
       end
     end
 
-    # Allows to set the logger.
-    # Defaults to logger, that outputs to `log/columns_trace.log` file
+    # Allows to set the reporter.
+    # Defaults to log reporter that outputs to `log/columns_trace.log` file
     # when inside a rails application.
     #
-    attr_accessor :logger
+    attr_accessor :reporter
 
     # @private
     attr_reader :backtrace_cleaner

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: columns_trace
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.3.0
 platform: ruby
 authors:
 - fatkodima
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2023-10-04 00:00:00.000000000 Z
+date: 2023-11-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: activerecord
@@ -35,10 +35,11 @@ files:
 - LICENSE.txt
 - README.md
 - lib/columns_trace.rb
+- lib/columns_trace/created_record.rb
+- lib/columns_trace/log_reporter.rb
 - lib/columns_trace/rails_integration.rb
 - lib/columns_trace/railtie.rb
 - lib/columns_trace/registry.rb
-- lib/columns_trace/reporter.rb
 - lib/columns_trace/sidekiq_integration.rb
 - lib/columns_trace/version.rb
 - test/dummy/tmp/development_secret.txt

data/lib/columns_trace/reporter.rb

@@ -1,53 +0,0 @@
-# frozen_string_literal: true
-
-module ColumnsTrace
-  # @private
-  class Reporter
-    def self.report(title)
-      new.report(title)
-    end
-
-    def report(title)
-      lines = []
-
-      Registry.entries.group_by(&:model).each do |model, entries|
-        lines.concat(lines_for_entries(model, entries))
-      end
-
-      if lines.any?
-        ColumnsTrace.logger.info("#{title}\n#{lines.join("\n")}")
-      end
-    end
-
-    private
-      def lines_for_entries(model, entries)
-        lines = []
-
-        entries.group_by(&:backtrace).each do |backtrace, grouped_entries|
-          records = grouped_entries.map(&:record)
-
-          accessed = accessed_fields(records)
-          unused = records.first.attributes.keys - accessed
-          unused.reject! { |column| ColumnsTrace.ignored_column?(model, column) }
-
-          if unused.any?
-            records_text = "record".pluralize(records.size)
-            lines << <<-MSG
-  #{records.size} #{model.name} #{records_text}: unused columns - #{format_columns(unused)}; used columns - #{format_columns(accessed)}
-  ↳ #{backtrace.join("\n  ")}
-            MSG
-          end
-        end
-
-        lines
-      end
-
-      def accessed_fields(records)
-        records.map(&:accessed_fields).flatten.uniq
-      end
-
-      def format_columns(columns)
-        columns.map(&:inspect).join(", ")
-      end
-  end
-end