blamestamp 0.9.0

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright 2012 Ryan Cavis
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
+LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
+OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

data/README.md

@@ -0,0 +1,137 @@
+Blamestamp
+=========
+
+Blamestamp is intended as an easy way to record the creating and latest-editing user for an Active Record.  It works similarly to the built-in Active Record timestamps module, but in a more configurable and predictable manner.  Column names are configurable, as are default values, in case you allow non logged-in users to edit some things.  Additionally, it allows configuration of when editing a record will update the blamestamps on a related record.
+
+
+Requirements
+------------
+
+### Ruby and Rails
+
+Requires Ruby version **>= 1.9.2** and Rails version **>= 3.0**
+
+### Current version limitations
+
+Currently only works with a combination of Devise, ActiveRecord and ActiveController.
+
+
+Installation
+------------
+
+Blamestamp should be installed as a gem in your app.  Currently, it is only available as the latest-build on github.  Fixed versions forth-coming.
+
+Include the gem in your Gemfile:
+
+    gem "blamestamp", :git => "https://github.com/cavis/blamestamp"
+
+
+Getting Started
+---------------
+
+### In your migrations:
+
+    class CreateFoos < ActiveRecord::Migration
+      def change
+        create_table :foos do |t|
+          t.string :bar
+          t.blamestamps
+        end
+      end
+    end
+
+Or, if modifying an existing model:
+
+    class AddBlamestampsToFoos < ActiveRecord::Migration
+      def up
+        change_table :foos do |t|
+          t.blamestamps
+        end
+      end
+      def down
+        drop_blamestamps :foos
+      end
+    end
+
+
+### In your model:
+
+    class Foo < ActiveRecord::Base
+      blameable
+    end
+
+
+Usage
+-----
+
+By default, blamestamps adds 4 columns to your models:
+
+* `blame_cre_at`
+* `blame_upd_at`
+* `blame_cre_by`
+* `blame_upd_by`
+
+When a record is created, `blame_cre_at` and `blame_cre_by` will be set.  If no remote-user is logged in (via a controller), `blame_cre_by` will be nil.  On initial creation, both `blame_upd_at` and `blame_upd_by` will be nil.
+
+When a record is updated for the first time (and every time after), `blame_upd_at` and `blame_upd_by` are modified.  Again, `blame_upd_by` will remain nil if there is no remote-user.
+
+Additionally, `blameable` adds 2 relations to your models:
+
+* `blame_cre_user`
+* `blame_upd_user`
+
+These are standard `belongs_to` associations, and will be nil unless the `_at` column is populated.
+
+
+Advanced Options
+----------------
+
+If that's not enough for you, there are several advanced config options available.
+
+### In your migrations:
+
+If you don't like the `blame` prefix on the columns, you can change it.  In this example it will create columns `blah_cre_at`, `blah_upd_at`, `blah_cre_by`, and `blah_upd_by`.
+
+    t.blamestamps :prefix => :blah
+
+### In your model:
+
+If you changed the prefix of the columns in your migration, you should let the model know about that too:
+
+    blameable :prefix => :blah
+
+Or, if you picked something completely off-the-wall in your migration, you can specify each of the 4 columns individually:
+
+    blameable :cre_at => :made_at, :upd_at => :changed_at, :cre_by => :invented_by, :upd_by => :hacked_by
+
+And if you don't like the default association names, you can define those too:
+
+    blameable :cre_user => :inventor, :upd_user => :hacker
+
+Finally, you can cascade modifications from a `blameable` model to one of its associations.  Whenever a record of the `blameable` class is inserted, updated, or deleted, the `upd_at`/`upd_by` columns on the associated record will be updated.  For example:
+
+    class Foo < ActiveRecord::Base
+      belongs_to :bar
+      belongs_to :project
+      blameable :cascade => [:project, :bar]
+    end
+
+Or, just specify a single cascade:
+
+    class Foo < ActiveRecord::Base
+      belongs_to :bar
+      belongs_to :project
+      blameable :cascade => :bar
+    end
+
+
+Issues and Contributing
+-----------------------
+
+Please, let me know about any bugs/feature-requests via the issues tracker.  And if you'd like to contribute, send me a note!  Thanks.
+
+
+License
+-------
+
+Blamestamp is free software, and may be redistributed under the MIT-LICENSE.

data/Rakefile

@@ -0,0 +1,38 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+rescue LoadError
+  require 'rdoc/rdoc'
+  require 'rake/rdoctask'
+  RDoc::Task = Rake::RDocTask
+end
+
+RDoc::Task.new(:rdoc) do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title    = 'Blamestamp'
+  rdoc.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  t.verbose = false
+end
+
+
+task :default => :test

data/lib/blamestamp/action_controller.rb

@@ -0,0 +1,24 @@
+require 'action_controller'
+
+module Blamestamp
+  module Blamer
+    extend ActiveSupport::Concern
+
+    included do
+      self.before_filter :set_blamer
+      self.after_filter :unset_blamer
+    end
+
+    def set_blamer
+      if user_signed_in?
+        Blamestamp::set_blame_user(current_user.id)
+      end
+    end
+
+    def unset_blamer
+      Blamestamp::unset_blame_user()
+    end
+  end
+end
+
+ActionController::Base.send :include, Blamestamp::Blamer

data/lib/blamestamp/active_record.rb

@@ -0,0 +1,84 @@
+require 'active_record'
+
+module Blamestamp
+  module Blameable
+    extend ActiveSupport::Concern
+
+    module ClassMethods
+      def blameable(options = {})
+        c = options_to_config(options)
+        class_attribute :blameable_config
+        self.blameable_config = c
+
+        # associations
+        self.belongs_to c[:cre_user], :class_name => c[:class], :foreign_key => c[:cre_by]
+        self.belongs_to c[:upd_user], :class_name => c[:class], :foreign_key => c[:upd_by]
+
+        # callbacks
+        self.before_create :blame_create
+        self.before_update :blame_update
+        self.after_destroy :blame_destroy
+      end
+
+      private
+
+      def options_to_config(opts)
+        prefix = opts[:prefix] || "blame"
+        cfg = {
+          :cre_at   => opts[:cre_at]   || "#{prefix}_cre_at".to_sym,
+          :upd_at   => opts[:upd_at]   || "#{prefix}_upd_at".to_sym,
+          :cre_by   => opts[:cre_by]   || "#{prefix}_cre_by".to_sym,
+          :upd_by   => opts[:upd_by]   || "#{prefix}_upd_by".to_sym,
+          :cre_user => opts[:cre_user] || "#{prefix}_cre_user".to_sym,
+          :upd_user => opts[:upd_user] || "#{prefix}_upd_user".to_sym,
+          :class    => opts[:class]    || "User".to_sym,
+          :cascade  => opts[:cascade]  || [],
+        }
+        cfg[:cascade] = [cfg[:cascade]] if !cfg[:cascade].kind_of?(Array)
+        return cfg
+      end
+    end
+
+    # main blamer workhorse
+    def blame_them!(at_key, by_key, force=false)
+      at_col = self.blameable_config[at_key]
+      by_col = self.blameable_config[by_key]
+
+      # only blame if it wasn't explicitly set
+      if force || !(self.changed - [at_col.to_s, by_col.to_s]).empty?
+        self[at_col] = Time.now
+        self[by_col] = Blamestamp::get_blame_user
+        return true
+      end
+
+      return false # nothing saved!
+    end
+
+    # cascade the blame up
+    def cascade_blame
+      self.blameable_config[:cascade].each do |assoc|
+        if self.send(assoc)
+          self.send(assoc).blame_them!(:upd_at, :upd_by, true)
+          self.send(assoc).save :validate => false
+        end
+      end
+    end
+
+    # create callback
+    def blame_create
+      self.cascade_blame() if self.blame_them!(:cre_at, :cre_by)
+    end
+
+    # update callback
+    def blame_update
+      self.cascade_blame() if self.blame_them!(:upd_at, :upd_by)
+    end
+
+    # destory callback
+    def blame_destroy
+      self.cascade_blame()
+    end
+  end
+end
+
+ActiveRecord::Base.send :include, Blamestamp::Blameable

data/lib/blamestamp/schema.rb

@@ -0,0 +1,37 @@
+module Blamestamp
+  module Schema
+    extend ActiveSupport::Concern
+
+    def blamestamps(options = {})
+      flds = options_to_fields(options)
+      column(flds[0], :datetime)
+      column(flds[1], :datetime)
+      column(flds[2], :integer)
+      column(flds[3], :integer)
+    end
+
+    def drop_blamestamps(tbl_name, options = {})
+      flds = options_to_fields(options)
+      remove_column tbl_name, :blame_cre_at
+      remove_column tbl_name, :blame_upd_at
+      remove_column tbl_name, :blame_cre_by
+      remove_column tbl_name, :blame_upd_by
+    end
+
+    private
+
+    def options_to_fields(opts)
+      prefix     = opts[:prefix] || 'blame'
+      cre_at_fld = opts[:cre_at] || "#{prefix}_cre_at"
+      upd_at_fld = opts[:upd_at] || "#{prefix}_upd_at"
+      cre_by_fld = opts[:cre_by] || "#{prefix}_cre_by"
+      upd_by_fld = opts[:upd_by] || "#{prefix}_upd_by"
+      return [cre_at_fld, upd_at_fld, cre_by_fld, upd_by_fld]
+    end
+  end
+end
+
+# include 3 times, so all variations migrations work
+ActiveRecord::ConnectionAdapters::AbstractAdapter.send(:include, Blamestamp::Schema)
+ActiveRecord::ConnectionAdapters::Table.send(:include, Blamestamp::Schema)
+ActiveRecord::ConnectionAdapters::TableDefinition.send(:include, Blamestamp::Schema)

data/lib/blamestamp/version.rb

@@ -0,0 +1,3 @@
+module Blamestamp
+  VERSION = "0.9.0"
+end

data/lib/blamestamp.rb

@@ -0,0 +1,26 @@
+module Blamestamp
+  def self.set_blame_user(id)
+    Thread.current[:blamer_id] = id
+  end
+  def self.get_blame_user
+    return Thread.current[:blamer_id]
+  end
+  def self.unset_blame_user
+    Thread.current[:blamer_id] = nil
+  end
+end
+
+# activerecord "blameable"
+if defined?(ActiveRecord)
+  require 'blamestamp/active_record'
+  require 'blamestamp/schema'
+else
+  raise "blamestamp only works with active_record"
+end
+
+# actioncontroller "blamer"
+if defined?(ActionController)
+  require 'blamestamp/action_controller'
+else
+  raise "blamestamp only works with action_controller"
+end

data/lib/tasks/blamestamp_tasks.rake

@@ -0,0 +1,4 @@
+# desc "Explaining what the task does"
+# task :blamestamp do
+#   # Task goes here
+# end

data/test/alligators_controller_test.rb

@@ -0,0 +1,60 @@
+require 'test_helper'
+
+class AlligatorsControllerTest < ActionController::TestCase
+  test "stamps on create" do
+    sign_in :user, users(:harold)
+    create_alligator("foo", projects(:secret))
+
+    assert_not_nil @alligator.gator_cre_at, "created_at not set"
+    assert_equal users(:harold).id, @alligator.gator_cre_by, "created_by not set"
+    assert_nil @alligator.gator_upd_at, "updated_at was set"
+    assert_nil @alligator.gator_upd_by, "updated_by was set"
+
+    assert_nil @alligator.project.blame_cre_at, "project created_at was set"
+    assert_nil @alligator.project.blame_cre_by, "project created_by was set"
+    assert_not_nil @alligator.project.blame_upd_at, "project updated_at not set"
+    assert_equal users(:harold).id, @alligator.project.blame_upd_by, "project updated_by not set"
+  end
+
+  test "stamps on update" do
+    sign_in :user, users(:isak)
+    update_alligator(alligators(:james), "foo")
+
+    assert_not_nil @alligator.gator_upd_at, "updated_at not set"
+    assert_equal users(:isak).id, @alligator.gator_upd_by, "updated_by not set"
+
+    assert_not_nil @alligator.project.blame_upd_at, "project updated_at not set"
+    assert_equal users(:isak).id, @alligator.project.blame_upd_by, "project updated_by not set"
+  end
+
+  test "stamps on destroy" do
+    sign_in :user, users(:cameron)
+    destroy_alligator(alligators(:james))
+    prj = Project.find(projects(:secret).id)
+
+    assert_not_nil prj.blame_upd_at, "project updated_at not set"
+    assert_equal users(:cameron).id, prj.blame_upd_by, "project updated_by not set"
+  end
+
+  private
+
+  # helper to create and set a new alligator
+  def create_alligator(name, project)
+    post :create, :alligator => {:name => name, :project_id => project.id}
+    assert_response :redirect, "create didn't redirect"
+    @alligator = assigns(:alligator)
+  end
+
+  # helper to update and set an existing alligator
+  def update_alligator(gat, name)
+    put :update, :id => gat.id, :alligator => {:name => name}
+    assert_response :redirect, "update didn't redirect"
+    @alligator = assigns(:alligator)
+  end
+
+  # helper to destroy an alligator
+  def destroy_alligator(gat)
+    put :destroy, :id => gat.id
+    assert_response :redirect, "destroy didn't redirect"
+  end
+end

data/test/blameable_test.rb

@@ -0,0 +1,114 @@
+require 'test_helper'
+
+class BlameableTest < ActiveSupport::TestCase
+  test "default options" do
+    assocs = Project.reflect_on_all_associations.collect {|a| a.name }
+    assert assocs.include?(:blame_cre_user), "doesn't include cre_user"
+    assert assocs.include?(:blame_upd_user), "doesn't include upd_user"
+
+    p = projects(:secret)
+    set_blamers(p, users(:harold), users(:isak))
+    assert_equal users(:harold).email, p.blame_cre_user.email, "incorrect cre_user"
+    assert_equal users(:isak).email, p.blame_upd_user.email, "incorrect upd_user"
+  end
+
+  test "prefix option" do
+    assocs = Alligator.reflect_on_all_associations.collect {|a| a.name }
+    assert assocs.include?(:gator_cre_user), "doesn't include cre_user"
+    assert assocs.include?(:gator_upd_user), "doesn't include upd_user"
+
+    a = alligators(:james)
+    set_blamers(a, users(:harold), users(:isak))
+    assert_equal users(:harold).email, a.gator_cre_user.email, "incorrect cre_user"
+    assert_equal users(:isak).email, a.gator_upd_user.email, "incorrect upd_user"
+  end
+
+  test "non array cascade option" do
+    a = alligators(:james)
+    assert_nil a.project.blame_cre_user, "project already blame-created"
+    assert_nil a.project.blame_upd_user, "project already blame-updated"
+
+    set_blamers(a, users(:isak), users(:isak))
+
+    assert_nil a.project.blame_cre_user, "project was blame-created"
+    assert_not_nil a.project.blame_upd_user, "project not blame-updated"
+    assert_equal users(:isak).email, a.project.blame_upd_user.email, "incorrect upd_user"
+  end
+
+  test "array cascade option" do
+    f = flags(:american)
+    assert_nil f.project.blame_cre_user, "project already blame-created"
+    assert_nil f.project.blame_upd_user, "project already blame-updated"
+    assert_nil f.alligator.gator_cre_user, "gator already blame-created"
+    assert_nil f.alligator.gator_upd_user, "gator already blame-updated"
+
+    set_blamers(f, users(:harold), users(:harold))
+
+    assert_nil f.project.blame_cre_user, "project was blame-created"
+    assert_not_nil f.project.blame_upd_user, "project not blame-updated"
+    assert_equal users(:harold).email, f.project.blame_upd_user.email, "incorrect upd_user"
+    assert_nil f.alligator.gator_cre_user, "gator was blame-created"
+    assert_not_nil f.alligator.gator_upd_user, "gator not blame-updated"
+    assert_equal users(:harold).email, f.alligator.gator_upd_user.email, "incorrect upd_user"
+  end
+
+  test "cre_at option" do
+    f = Flag.new(:origin => 'aoeu')
+    assert_nil f.made_at, "already has cre_at"
+    f.save()
+    assert_not_nil f.made_at, "didn't set cre_at"
+  end
+
+  test "upd_at option" do
+    f = flags(:semaphore)
+    f.origin = "something else"
+    assert_nil f.changed_at, "already has upd_at"
+    f.save()
+    assert_not_nil f.changed_at, "didn't set upd_at"
+  end
+
+  test "cre_by option" do
+    f = Flag.new(:origin => 'aoeu')
+    assert_nil f.made_by, "already has cre_by"
+    f.save()
+    assert_not_nil f.made_by, "didn't set cre_by"
+  end
+
+  test "upd_by option" do
+    f = flags(:semaphore)
+    f.origin = "something else"
+    assert_nil f.hacked_by, "already has upd_by"
+    f.save()
+    assert_not_nil f.hacked_by, "didn't set upd_by"
+  end
+
+  test "cre_user option" do
+    assocs = Flag.reflect_on_all_associations.collect {|f| f.name }
+    assert assocs.include?(:maker), "doesn't include cre_user"
+
+    f = flags(:semaphore)
+    set_blamers(f, users(:cameron), users(:cameron))
+    assert_equal users(:cameron).email, f.maker.email, "incorrect cre_user"
+  end
+
+  test "upd_user option" do
+    assocs = Flag.reflect_on_all_associations.collect {|f| f.name }
+    assert assocs.include?(:hacker), "doesn't include upd_user"
+
+    f = flags(:semaphore)
+    set_blamers(f, users(:cameron), users(:cameron))
+    assert_equal users(:cameron).email, f.hacker.email, "incorrect upd_user"
+  end
+
+  private
+
+  def set_blamers(rec, cre_user, upd_user)
+    Blamestamp::set_blame_user(cre_user.id)
+    rec.blame_them!(:cre_at, :cre_by, true)
+    rec.cascade_blame
+    Blamestamp::set_blame_user(upd_user.id)
+    rec.blame_them!(:upd_at, :upd_by, true)
+    rec.cascade_blame
+  end
+
+end

data/test/blamestamp_test.rb

@@ -0,0 +1,7 @@
+require 'test_helper'
+
+class BlamestampTest < ActiveSupport::TestCase
+  test "exists" do
+    assert_kind_of Module, Blamestamp, "blamestamp isn't what it seems to be"
+  end
+end

data/test/devise_works_test.rb

@@ -0,0 +1,20 @@
+require 'test_helper'
+
+class DeviseWorksTest < ActionController::TestCase
+  setup do
+    @controller = HomeController.new
+  end
+
+  test "logged out" do
+    get :index
+    assert_response :success
+    assert_select "#loggedout"
+  end
+
+  test "login" do
+    sign_in :user, users(:harold)
+    get :index
+    assert_response :success
+    assert_select "#loggedin"
+  end
+end