arca 2.2.0 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: b0591095b4b348fcbd76cf72ef3cea8aeecb8016
-  data.tar.gz: bd32d70f3788e5238761d3368b6944b923860c54
+SHA256:
+  metadata.gz: 326dbd7961f9ccfe0b39d77572d3fcc6599179feaf88a81f3fdfdc64ce0bb8e2
+  data.tar.gz: e0298827379b3759f81eaac23fb9d626b8ce20ae4150a4c44b01379157c6263a
 SHA512:
-  metadata.gz: 9ea28b0b452751d96980314871b79df23b5ea261e9defbc9e3f331690d1c5ca4f4fee7b8c6c65461298faab770034c1c58e752b89cd9f5aa833b032b784a5c5b
-  data.tar.gz: 5477fd14ed651d2681b8167db4ef3ee5ea60ae7246f73cb9e9e36c025df1f2747678d1db410b47113d8f78985bde696cf25b2cfee7e4b69bd90e92f35f001250
+  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.2.0"
+  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/collector.rb

@@ -33,8 +33,8 @@ module Arca
             # Duplicate args before modifying.
             args_copy = args.dup
 
-            # Add target_symbol :inline to args_copy if a block, Proc, or Class
-            # 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(:inline)
             elsif args_copy.first.kind_of?(Proc)

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.

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: arca
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  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: