arca 2.1.3 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: 1becb49c860d2d307b0a29e91a2d93e0bfe86845
-  data.tar.gz: b230fe2a8c7d72fc0d84767de6546d67ea707426
+SHA256:
+  metadata.gz: 326dbd7961f9ccfe0b39d77572d3fcc6599179feaf88a81f3fdfdc64ce0bb8e2
+  data.tar.gz: e0298827379b3759f81eaac23fb9d626b8ce20ae4150a4c44b01379157c6263a
 SHA512:
-  metadata.gz: fc86642a2abba3e45f437b4607ab54e775a009ea35611202907a3af1d7da8a59fc0fadc110467a5c66ce080f6133e9e409071c50c34254d1fa4d2611392f3777
-  data.tar.gz: bd855300d7bc35f2d5029ec4749cf72572f626a675402f4af92d759b81bb5821cf8b3fca86b1675fa59cb3cfd6afc8d38e52a192a68031a11096867e160094b2
+  metadata.gz: 421d318fdbabf614179e883b5b009d3f7f8a560dbaed1c885ddcc09d14f656f774b162f3d111c576cf0b2fc5f63bfe913e7be09cb043c1c84a8fc18961a9a1c4
+  data.tar.gz: 6d9f740fb81d86ef2b2ede9b803ac04e77a3327b2053f48e4cbcbf551217293939cacba68b0c5ef87e47e8c90972eb7afe96ead015364011b7d34a21c0f6dae1

data/README.md

@@ -1,6 +1,6 @@
 # ActiveRecord Callback Analyzer
 
-Arca is a callback analyzer for ActiveRecord models ideally suited for digging yourself out of callback hell. At best it will help you move towards a [more maintainable design](http://adequate.io/culling-the-activerecord-lifecycle) and at worst it can be used in your test suite to give you feedback when callbacks change.
+Arca is a callback analyzer for ActiveRecord models ideally suited for digging yourself out of callback hell. At best it will help you move towards a [more maintainable design](https://web.archive.org/web/20161016162603/http://adequate.io/culling-the-activerecord-lifecycle) and at worst it can be used in your test suite to give you feedback when callbacks change.
 
 Arca helps you answer questions like:
 
@@ -10,6 +10,8 @@ Arca helps you answer questions like:
 
 The Arca library has two main components, the collector and the reporter. Include the collector module in ActiveRecord::Base before your models are loaded.
 
+At GitHub, we test callbacks by whitelisting existing callbacks, and adding a lint test to ensure new callbacks are not added without review. The [examples](examples) folder is a good starting point.
+
 ## Requirements
 
 ![travis-ci build status](https://travis-ci.org/jonmagic/arca.svg)
@@ -34,7 +36,9 @@ class ActiveRecord::Base
   include Arca::Collector
 end
 
-# load your app
+# load your app. It's important to setup before loading your models because Arca
+# works by wrapping itself around the callback method definitions (before_save,
+# after_save, etc) and then records how and where those methods are used.
 ```
 
 In this example the `Annoucements` module is included in `Ticket` and defines it's own callback.
@@ -212,6 +216,12 @@ have to update this test to make it pass.
 ---------------------------------------------
 ```
 
+## Contributors
+
+- [@jonmagic](https://github.com/jonmagic)
+- [@jch](https://github.com/jch)
+- [@bensheldon](https://github.com/bensheldon)
+
 ## License
 
 The MIT License (MIT)

data/arca.gemspec

@@ -1,6 +1,6 @@
 Gem::Specification.new do |spec|
   spec.name          = "arca"
-  spec.version       = "2.1.3"
+  spec.version       = "2.3.0"
   spec.date          = "2015-08-07"
   spec.summary       = "ActiveRecord callback analyzer"
   spec.description   = "Arca is a callback analyzer for ActiveRecord ideally suited for digging yourself out of callback hell"

data/examples/active_record_lint_test.rb

@@ -0,0 +1,42 @@
+require "minitest"
+
+class ActiveRecordLintTest < Minitest::Test
+  def test_callbacks_must_be_defined_in_the_base_model_file
+    whitelist_path = File.expand_path("../active_record_callback_whitelist.txt", __FILE__)
+    whitelisted_callbacks = if File.exists?(whitelist_path)
+      File.read(whitelist_path).split("\n")
+    else
+      ""
+    end
+
+    # git grep... list classes with a parent. Does not handle classes nested within a module
+    # xargs... arca analyze. We skip line numbers so we can diff the results
+    # grep... filter for callbacks defined in external files or callbacks without names
+    #
+    # To update the whitelist, save the output up to script/audit-callbacks.
+    callback_output = IO.popen(<<-CMD).read
+      git grep -h '^class.*< ' -- '*.rb' | cut -d' ' -f 2 | sort -u | \
+      xargs bundle exec audit-callbaks.rb --skip-line-num | \
+      grep -E 'external:true|block$'
+    CMD
+
+    actual_callbacks = callback_output.split("\n")
+
+    new_bad_callbacks = actual_callbacks - whitelisted_callbacks
+    unnecessary_whitelist_entries = whitelisted_callbacks - actual_callbacks
+
+    message = ""
+    if new_bad_callbacks.any?
+      message << "The following ActiveRecord callbacks must be defined in the base model file with a named method:\n\n"
+      message << new_bad_callbacks.join("\n")
+    end
+
+    if unnecessary_whitelist_entries.any?
+      message << "\n\n" unless message.empty?
+      message << "Hooray! You removed a bad ActiveRecord callback. Please update #{whitelist_path} and remove the following\n\n"
+      message << unnecessary_whitelist_entries.join("\n")
+    end
+
+    assert message.empty?, message
+  end
+end

data/examples/audit-callbacks.rb

@@ -0,0 +1,75 @@
+# Prints a list of Active Record callbacks for the given models
+#
+# Usage:
+#   bundle exec audit-callbacks.rb [--skip-line-num] [Model1 Model2...]
+#
+skip_line_num = false
+if ARGV.first == "--skip-line-num"
+  ARGV.shift
+  skip_line_num = true
+end
+
+unless ARGV.size > 0
+  $stderr.puts "No models specified. Try script/audit-callbacks User Issue."
+  exit 1
+end
+
+# Arca must be required after ActiveRecord, but before the environment loads so
+# we can install Arca::Collector.
+require "active_record"
+require "arca"
+class ActiveRecord::Base
+  include Arca::Collector
+end
+
+require "config/environment"
+
+# Returns a formatted string of a callback analysis.
+#
+# Examples:
+#
+# An unnamed (block) before_destroy callback defined in the same file as the model
+# Ability before_destroy app/models/ability.rb external:false block
+#
+# A after_destroy callback named `dereference_asset` defined in a file outside of the model (external:true)
+# Avatar after_destroy app/models/asset_uploadable.rb external:true dereference_asset
+#
+# A before_save callback defined by a callback class
+# IssueComment before_save app/models/referrer.rb external:true Referrer::ReferenceMentionsCallback
+#
+def format_callback(callback, skip_line_num:)
+  path = Arca.relative_path(callback.callback_file_path)
+  path << ":#{callback.callback_line_number}" unless skip_line_num
+
+  # Arca outputs object ids which triggers a diff
+  # e.g. #<Referrer::ReferenceMentionsCallback:0x007f8bca3a1b48>
+  target = if match = /#<(.+):.+>/.match(callback.target_symbol.to_s)
+    match[1]
+  else
+    callback.target_symbol
+  end
+
+  [
+    callback.model.name,
+    callback.callback_symbol,
+    path,
+    "external:#{callback.external_callback?}",
+    target
+  ].map(&:to_s).join(" ")
+end
+
+ARGV.each do |model_name|
+  begin
+    model_class = model_name.constantize
+  rescue NameError # test classes
+    next
+  end
+
+  next unless model_class.ancestors.include?(ActiveRecord::Base)
+
+  Arca[model_class].analyzed_callbacks.each do |callback_symbol, callbacks|
+    callbacks.each do |callback|
+      puts format_callback(callback, skip_line_num: skip_line_num)
+    end
+  end
+end

data/lib/arca/callback_analysis.rb

@@ -80,7 +80,7 @@ module Arca
     # Public: Boolean representing whether the callback target is located in the
     # same file where the callback is defined.
     def external_target?
-      return false if target_symbol == :block
+      return false if target_symbol == :inline
       target_file_path != callback_file_path
     end
 

data/lib/arca/collector.rb

@@ -33,9 +33,21 @@ module Arca
             # Duplicate args before modifying.
             args_copy = args.dup
 
-            # Add target_symbol :block to args_copy if a block was given.
+            # Add target_symbol :inline to args_copy if given a block or Proc and 
+            # class name if a class or instance was given.
             if block
-              args_copy.unshift(:block)
+              args_copy.unshift(:inline)
+            elsif args_copy.first.kind_of?(Proc)
+              args_copy.shift
+              args_copy.unshift(:inline)
+            elsif !args_copy.first.kind_of?(Symbol)
+              class_or_instance = args_copy.shift
+
+              if class_or_instance.class == Class
+                args_copy.unshift(class_or_instance.name.to_sym)
+              else
+                args_copy.unshift(class_or_instance.class.name.to_sym)
+              end
             end
 
             # Get the options hash from the end of the args Array if it exists.
@@ -78,7 +90,6 @@ module Arca
                 :conditional_symbol             => conditional_symbol,
                 :conditional_target_symbol      => conditional_target_symbol
               }
-
             end
 
             # Bind the callback method to self and call it with args.

data/lib/arca/model.rb

@@ -15,9 +15,11 @@ module Arca
     # they are used in the life cycle of an ActiveRecord model.
     CALLBACKS = [
       :after_initialize, :after_find, :after_touch, :before_validation, :after_validation,
-      :before_save, :around_save, :after_save, :before_create, :around_create,
-      :after_create, :before_update, :around_update, :after_update,
-      :before_destroy, :around_destroy, :after_destroy, :after_commit, :after_rollback
+      :before_save, :around_save, :after_save, :after_save_commit,
+      :before_create, :around_create, :after_create, :after_create_commit,
+      :before_update, :around_update, :after_update, :after_update_commit,
+      :before_destroy, :around_destroy, :after_destroy, :after_destroy_commit,
+      :after_commit, :after_rollback
     ]
 
     # Public: ActiveRecord model class.

data/test/fixtures/announcements.rb

@@ -1,8 +1,19 @@
+class SomeCallbackClass
+  def after_destroy(record)
+    puts "after_destroy announcement callback"
+  end
+end
+
 module Announcements
   def self.included(base)
     base.class_eval do
-      before_save { puts "pre-save announcement callback" }
+      before_save { puts "before_save announcement callback" }
       after_save :announce_save
+
+      around_save lambda { puts "around_save announcement callback" }
+      before_destroy -> { puts "before_destroy announcement callback" }
+
+      after_destroy SomeCallbackClass.new
     end
   end
 

data/test/lib/arca/callback_analysis_test.rb

@@ -75,7 +75,7 @@ class Arca::CallbackAnalysisTest < Minitest::Test
   end
 
   def test_target_line_number
-    assert_equal 9, announce_save.target_line_number
+    assert_equal 20, announce_save.target_line_number
     assert_equal 8, set_title.target_line_number
     assert_equal 16, upcase_title.target_line_number
   end
@@ -87,7 +87,7 @@ class Arca::CallbackAnalysisTest < Minitest::Test
   end
 
   def test_lines_to_target
-    assert_equal 5, announce_save.lines_to_target
+    assert_equal 16, announce_save.lines_to_target
     assert_equal 3, set_title.lines_to_target
     assert_equal 10, upcase_title.lines_to_target
   end

data/test/lib/arca/collector_test.rb

@@ -6,11 +6,15 @@ class Arca::CollectorTest < Minitest::Test
     assert_equal 1, callbacks[:after_save].size
     assert_equal 4, callbacks[:before_save].size
     assert_equal 1, callbacks[:after_commit].size
+    assert_equal 1, callbacks[:around_save].size
+    assert_equal 1, callbacks[:before_destroy].size
+    assert_equal 1, callbacks[:after_destroy].size
+
 
     callback = callbacks[:after_save][0]
     assert_equal :after_save, callback[:callback_symbol]
     assert_match "test/fixtures/announcements.rb", callback[:callback_file_path]
-    assert_equal 5, callback[:callback_line_number]
+    assert_equal 11, callback[:callback_line_number]
     assert_equal :announce_save, callback[:target_symbol]
     assert_nil callback[:conditional_symbol]
     assert_nil callback[:conditional_target_symbol]
@@ -18,8 +22,8 @@ class Arca::CollectorTest < Minitest::Test
     callback = callbacks[:before_save][0]
     assert_equal :before_save, callback[:callback_symbol]
     assert_match "test/fixtures/announcements.rb", callback[:callback_file_path]
-    assert_equal 4, callback[:callback_line_number]
-    assert_equal :block, callback[:target_symbol]
+    assert_equal 10, callback[:callback_line_number]
+    assert_equal :inline, callback[:target_symbol]
     assert_nil callback[:conditional_symbol]
     assert_nil callback[:conditional_target_symbol]
 
@@ -54,6 +58,30 @@ class Arca::CollectorTest < Minitest::Test
     assert_equal :update_timeline, callback[:target_symbol]
     assert_equal :on, callback[:conditional_symbol]
     assert_equal [:create, :destroy], callback[:conditional_target_symbol]
+
+    callback = callbacks[:around_save][0]
+    assert_equal :around_save, callback[:callback_symbol]
+    assert_match "test/fixtures/announcements.rb", callback[:callback_file_path]
+    assert_equal 13, callback[:callback_line_number]
+    assert_equal :inline, callback[:target_symbol]
+    assert_nil callback[:conditional_symbol]
+    assert_nil callback[:conditional_target_symbol]
+
+    callback = callbacks[:before_destroy][0]
+    assert_equal :before_destroy, callback[:callback_symbol]
+    assert_match "test/fixtures/announcements.rb", callback[:callback_file_path]
+    assert_equal 14, callback[:callback_line_number]
+    assert_equal :inline, callback[:target_symbol]
+    assert_nil callback[:conditional_symbol]
+    assert_nil callback[:conditional_target_symbol]
+
+    callback = callbacks[:after_destroy][0]
+    assert_equal :after_destroy, callback[:callback_symbol]
+    assert_match "test/fixtures/announcements.rb", callback[:callback_file_path]
+    assert_equal 16, callback[:callback_line_number]
+    assert_equal :SomeCallbackClass, callback[:target_symbol]
+    assert_nil callback[:conditional_symbol]
+    assert_nil callback[:conditional_target_symbol]
   end
 
   def test_callback_is_reapplied_with_original_args

data/test/lib/arca/model_test.rb

@@ -33,24 +33,24 @@ class Arca::ModelTest < Minitest::Test
   end
 
   def test_analyzed_callbacks_array
-    assert_equal 6, model.analyzed_callbacks_array.size
+    assert_equal 9, model.analyzed_callbacks_array.size
     assert model.analyzed_callbacks_array[0].is_a?(Arca::CallbackAnalysis)
   end
 
   def test_analyzed_callbacks_count
-    assert_equal 6, model.analyzed_callbacks_count
+    assert_equal 9, model.analyzed_callbacks_count
   end
 
   def test_lines_between_count
-    assert_equal 6, model.lines_between_count
+    assert_equal 16, model.lines_between_count
   end
 
   def test_external_callbacks_count
-    assert_equal 2, model.external_callbacks_count
+    assert_equal 5, model.external_callbacks_count
   end
 
   def test_external_targets_count
-    assert_equal 0, model.external_targets_count
+    assert_equal 1, model.external_targets_count
   end
 
   def test_external_conditionals_count

data/test/lib/arca/report_test.rb

@@ -22,6 +22,6 @@ class Arca::ReportTest < Minitest::Test
   end
 
   def test_calculated_permutations
-    assert_equal 3, report.calculated_permutations
+    assert_equal 6, report.calculated_permutations
   end
 end

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: arca
 version: !ruby/object:Gem::Version
-  version: 2.1.3
+  version: 2.3.0
 platform: ruby
 authors:
 - Jonathan Hoyt
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
 date: 2015-08-07 00:00:00.000000000 Z
@@ -79,6 +79,8 @@ files:
 - README.md
 - Rakefile
 - arca.gemspec
+- examples/active_record_lint_test.rb
+- examples/audit-callbacks.rb
 - gemfiles/Gemfile_activerecord-3.2
 - gemfiles/Gemfile_activerecord-4.2
 - lib/arca.rb
@@ -99,7 +101,7 @@ homepage: https://github.com/jonmagic/arca
 licenses:
 - MIT
 metadata: {}
-post_install_message: 
+post_install_message:
 rdoc_options: []
 require_paths:
 - lib
@@ -114,9 +116,8 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.2.2
-signing_key: 
+rubygems_version: 3.5.5
+signing_key:
 specification_version: 4
 summary: ActiveRecord callback analyzer
 test_files: