arca 2.2.0 → 2.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: b0591095b4b348fcbd76cf72ef3cea8aeecb8016
-  data.tar.gz: bd32d70f3788e5238761d3368b6944b923860c54
+SHA256:
+  metadata.gz: 9653b1c97af42cfa6437b583a2b7a24f99397ad8f6b8f9dc6b6ff39897187187
+  data.tar.gz: 46afe8ebabfbd4cad7d08c78f0303226409984adce61f0b12240bcd8b318ca1a
 SHA512:
-  metadata.gz: 9ea28b0b452751d96980314871b79df23b5ea261e9defbc9e3f331690d1c5ca4f4fee7b8c6c65461298faab770034c1c58e752b89cd9f5aa833b032b784a5c5b
-  data.tar.gz: 5477fd14ed651d2681b8167db4ef3ee5ea60ae7246f73cb9e9e36c025df1f2747678d1db410b47113d8f78985bde696cf25b2cfee7e4b69bd90e92f35f001250
+  metadata.gz: dd5e0a8bab34fbcd7c6f8b5ca4156f64adbbfa0d9a94d33d791b91f90b0962cb94c8649ec94a861993f4170b88c0ce63239ea1de6f78ccca15f4e39bd7d7a7ed
+  data.tar.gz: 7abcf185d338042bfabe79d3f6875e943b373af87a24d2b56859e4202b7eb7021e5b552fc6b9da5ef68ff60aae0a6806dce5e3045b669eacc13a11f60e44877e

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,13 @@ 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)
+- [@jasonkim](https://github.com/jasonkim)
+
 ## 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.1"
   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"
@@ -13,8 +13,8 @@ Gem::Specification.new do |spec|
   spec.homepage      = "https://github.com/jonmagic/arca"
   spec.license       = "MIT"
 
-  spec.add_development_dependency "activerecord",  "~> 4.2"
-  spec.add_development_dependency "minitest",      "~> 5.7"
-  spec.add_development_dependency "pry",           "~> 0.10"
-  spec.add_development_dependency "rake",          "~> 10.4"
+  spec.add_development_dependency "activerecord",  "~> 7.1"
+  spec.add_development_dependency "minitest",      "~> 5.22"
+  spec.add_development_dependency "pry",           "~> 0.14"
+  spec.add_development_dependency "rake",          "~> 13.2"
 end

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

@@ -6,7 +6,7 @@ module Arca
 
     # Internal: Regular expression used for extracting the file path and line
     # number from a caller line.
-    ARCA_CALLBACK_FINDER_REGEXP = /\A(.+)\:(\d+)\:in\s`.+'\z/
+    ARCA_CALLBACK_FINDER_REGEXP = /\A(.+)\:(\d+)\:in\s[`'].+'\z/
     private_constant :ARCA_CALLBACK_FINDER_REGEXP
 
     # Internal: Array of conditional symbols.
@@ -21,7 +21,7 @@ module Arca
         end
 
         # Find the callback methods defined on this class.
-        callback_method_symbols = singleton_methods.grep /^(after|around|before)\_/
+        callback_method_symbols = singleton_methods.grep(/^(after|around|before)\_/)
 
         callback_method_symbols.each do |callback_symbol|
           # Find the UnboundMethod for the callback.
@@ -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)
@@ -58,7 +58,7 @@ module Arca
 
             # Extract the model file path from the caller stack.
             caller.each do |line|
-              if match = /\A(.+):\d+:in\s`<class:#{name.split("::").last}>'/.match(line)
+              if match = /\A(.+):\d+:in\s[`']<class:#{name.split("::").last}>'/.match(line)
                 self.arca_callback_data[:model_file_path] = match[1]
                 break
               end

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/lib/arca/report.rb

@@ -61,7 +61,7 @@ module Arca
     # from conditionals for an instance of the model being reported during the
     # lifecycle of the object.
     def calculated_permutations
-      permutations = model.analyzed_callbacks.inject([]) do |results, (key, analyzed_callbacks)|
+      model.analyzed_callbacks.inject([]) do |results, (key, analyzed_callbacks)|
         results << 2 ** number_of_unique_conditionals(analyzed_callbacks)
       end.sum - number_of_unique_conditionals(model.analyzed_callbacks_array)
     end

metadata

@@ -1,11 +1,11 @@
 --- !ruby/object:Gem::Specification
 name: arca
 version: !ruby/object:Gem::Version
-  version: 2.2.0
+  version: 2.3.1
 platform: ruby
 authors:
 - Jonathan Hoyt
-autorequire: 
+autorequire:
 bindir: bin
 cert_chain: []
 date: 2015-08-07 00:00:00.000000000 Z
@@ -16,56 +16,56 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.2'
+        version: '7.1'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.2'
+        version: '7.1'
 - !ruby/object:Gem::Dependency
   name: minitest
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.7'
+        version: '5.22'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '5.7'
+        version: '5.22'
 - !ruby/object:Gem::Dependency
   name: pry
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.10'
+        version: '0.14'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '0.10'
+        version: '0.14'
 - !ruby/object:Gem::Dependency
   name: rake
   requirement: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.4'
+        version: '13.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '10.4'
+        version: '13.2'
 description: Arca is a callback analyzer for ActiveRecord ideally suited for digging
   yourself out of callback hell
 email: jonmagic@gmail.com
@@ -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.3
+signing_key:
 specification_version: 4
 summary: ActiveRecord callback analyzer
 test_files: