whodunit 0.1.0

data/README.md

@@ -0,0 +1,376 @@
+# Whodunit
+
+Lightweight creator/updater/deleter tracking for Rails ActiveRecord models.
+
+> **Fun Fact**: The term "whodunit" was coined by literary critic Donald Gordon in 1930 when reviewing a murder mystery novel for _American News of Books_. He described Milward Kennedy's _Half Mast Murder_ as "a satisfactory whodunit" - the first recorded use of this now-famous term for mystery stories! _([Source: Wikipedia](https://en.wikipedia.org/wiki/Whodunit))_
+
+## Overview
+
+Whodunit provides simple auditing for Rails applications by tracking who created, updated, and deleted records. Unlike heavyweight solutions like PaperTrail or Audited, Whodunit focuses solely on user tracking with zero performance overhead.
+
+## Requirements
+
+- Ruby 3.1.1+ (tested on 3.1.1, 3.2.0, 3.3.0, 3.4). See the [the ruby-version matrix strategy of the CI workflow](https://github.com/kanutocd/whodunit/blob/main/.github/workflows/ci.yml#L15).
+- Rails 7.2+ (tested on 7.2, 8.2, and edge)
+- ActiveRecord for database operations
+
+## Features
+
+- **Lightweight**: Only tracks user IDs, no change history or versioning
+- **Smart Soft-Delete Detection**: Automatically detects Discard, Paranoia, and custom soft-delete implementations
+- **Thread-Safe**: Uses Rails `CurrentAttributes` pattern for user context
+- **Zero Dependencies**: Only requires Rails 7.2+
+- **Performance Focused**: No default scopes or method overrides
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'whodunit'
+```
+
+And then execute:
+
+    $ bundle install
+
+## Quick Start
+
+### 1. Add Stamp Columns
+
+Generate a migration to add the tracking columns:
+
+```ruby
+class AddStampsToUsers < ActiveRecord::Migration[7.0]
+  def change
+    add_whodunit_stamps :users  # Adds creator_id, updater_id columns
+  end
+end
+```
+
+For models with soft-delete, deleter tracking is automatically detected:
+
+```ruby
+class AddStampsToDocuments < ActiveRecord::Migration[7.0]
+  def change
+    add_whodunit_stamps :documents  # Adds creator_id, updater_id, deleter_id (if soft-delete detected)
+  end
+end
+```
+
+### 2. Include Stampable in Models
+
+```ruby
+class User < ApplicationRecord
+  include Whodunit::Stampable
+end
+
+class Document < ApplicationRecord
+  include Discard::Model  # or acts_as_paranoid, etc.
+  include Whodunit::Stampable  # Automatically detects soft-delete!
+end
+```
+
+### 3. Set Up Controller Integration
+
+```ruby
+class ApplicationController < ActionController::Base
+  # Whodunit::ControllerMethods is automatically included via Railtie
+  # It will automatically set the current user for stamping
+end
+```
+
+## Usage
+
+Once set up, stamping happens automatically:
+
+```ruby
+# Creating records
+user = User.create!(name: "Ken")
+# => Sets user.creator_id to current_user.id
+
+# Updating records
+user.update!(name: "Sophia")
+# => Sets user.updater_id to current_user.id
+
+# Soft deleting (if soft-delete gem is detected)
+document.discard
+# => Sets document.deleter_id to current_user.id
+```
+
+Access the stamp information via associations:
+
+```ruby
+user.creator   # => User who created this record
+user.updater   # => User who last updated this record
+user.deleter   # => User who deleted this record (if soft-delete enabled)
+```
+
+## Smart Soft-Delete Detection
+
+Whodunit automatically detects popular soft-delete solutions:
+
+- **Discard** (`gem 'discard'`)
+- **Paranoia** (`gem 'paranoia'`)
+- **ActsAsParanoid** (`gem 'acts_as_paranoid'`)
+- **Custom implementations** with timestamp columns like `deleted_at`, `discarded_at`, etc.
+
+## Configuration
+
+```ruby
+# config/initializers/whodunit.rb
+Whodunit.configure do |config|
+  config.user_class = 'Account'             # Default: 'User'
+  config.creator_column = :created_by_id    # Default: :creator_id
+  config.updater_column = :updated_by_id    # Default: :updater_id
+  config.deleter_column = :deleted_by_id    # Default: :deleter_id
+  config.auto_detect_soft_delete = false   # Default: true
+
+  # Column data type configuration
+  config.column_data_type = :integer       # Default: :bigint (applies to all columns)
+  config.creator_column_type = :string     # Default: nil (uses column_data_type)
+  config.updater_column_type = :uuid       # Default: nil (uses column_data_type)
+  config.deleter_column_type = :integer    # Default: nil (uses column_data_type)
+end
+```
+
+### Data Type Configuration
+
+By default, all stamp columns use `:bigint` data type. You can customize this in several ways:
+
+- **Global**: Set `column_data_type` to change the default for all columns
+- **Individual**: Set specific column types to override the global default
+- **Per-migration**: Override types on a per-migration basis (see Migration Helpers)
+
+## Manual User Setting
+
+For background jobs, tests, or special scenarios:
+
+```ruby
+# Temporarily set user
+Whodunit::Current.user = User.find(123)
+MyModel.create!(name: "test")  # Will be stamped with user 123
+
+# Within a block
+controller.with_whodunit_user(admin_user) do
+  Document.create!(title: "Admin Document")
+end
+
+# Disable stamping temporarily
+controller.without_whodunit_user do
+  Document.create!(title: "System Document")  # No stamps
+end
+```
+
+## Migration Helpers
+
+```ruby
+# Basic usage (uses configured data types)
+class CreatePosts < ActiveRecord::Migration[7.0]
+  def change
+    create_table :posts do |t|
+      t.string :title
+      t.whodunit_stamps  # Adds creator_id, updater_id with configured types
+      t.timestamps
+    end
+  end
+end
+
+# Custom data types per migration
+class CreateUsers < ActiveRecord::Migration[7.0]
+  def change
+    create_table :users do |t|
+      t.string :email
+      t.whodunit_stamps include_deleter: true,
+                        creator_type: :uuid,
+                        updater_type: :string,
+                        deleter_type: :integer
+      t.timestamps
+    end
+  end
+end
+
+# Add to existing table with custom types
+class AddStampsToExistingTable < ActiveRecord::Migration[7.0]
+  def change
+    add_whodunit_stamps :existing_table,
+                        include_deleter: :auto,
+                        creator_type: :string,
+                        updater_type: :uuid
+  end
+end
+
+# Mixed approach - some custom, some default
+class CreateDocuments < ActiveRecord::Migration[7.0]
+  def change
+    create_table :documents do |t|
+      t.string :title
+      t.whodunit_stamps creator_type: :uuid  # Only override creator, others use defaults
+      t.timestamps
+    end
+  end
+end
+```
+
+### Data Type Options
+
+Common data types you can use:
+
+- `:bigint` (default) - 64-bit integer, suitable for large user bases
+- `:integer` - 32-bit integer, suitable for smaller applications
+- `:string` - For string-based user identifiers
+- `:uuid` - For UUID-based user systems
+- Any other Rails column type
+
+## Controller Methods
+
+Skip stamping for specific actions:
+
+```ruby
+class ApiController < ApplicationController
+  skip_whodunit_for :index, :show
+end
+```
+
+Only stamp specific actions:
+
+```ruby
+class ReadOnlyController < ApplicationController
+  whodunit_only_for :create, :update, :destroy
+end
+```
+
+## Thread Safety
+
+Whodunit uses Rails `CurrentAttributes` for thread-safe user context:
+
+```ruby
+# Each thread maintains its own user context
+Thread.new { Whodunit::Current.user = user1; create_records }
+Thread.new { Whodunit::Current.user = user2; create_records }
+```
+
+## Testing
+
+In your tests, you can set the user context:
+
+```ruby
+# RSpec
+before do
+  Whodunit::Current.user = create(:user)
+end
+
+# Or within specific tests
+it "tracks creator" do
+  user = create(:user)
+  Whodunit::Current.user = user
+
+  post = create(:post)
+  expect(post.creator).to eq(user)
+end
+```
+
+## Comparisons
+
+| Feature               | Whodunit | PaperTrail | Audited |
+| --------------------- | -------- | ---------- | ------- |
+| User tracking         | ✅       | ✅         | ✅      |
+| Change history        | ❌       | ✅         | ✅      |
+| Performance overhead  | None     | High       | Medium  |
+| Soft-delete detection | ✅       | ❌         | ❌      |
+| Setup complexity      | Low      | Medium     | Medium  |
+
+## Documentation
+
+Complete API documentation is available at: **[https://kanutocd.github.io/whodunit](https://kanutocd.github.io/whodunit)**
+
+The documentation includes:
+
+- Comprehensive API reference with examples
+- Configuration options and their defaults
+- Migration helper methods
+- Controller integration patterns
+- Advanced usage scenarios
+
+To generate documentation locally:
+
+```bash
+bundle exec yard doc
+open doc/index.html
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `bundle exec rspec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec gem build whodunit.gemspec && gem install ./whodunit-*.gem`.
+
+### Testing
+
+```bash
+# Run all tests
+bundle exec rspec
+
+# Run tests with coverage
+COVERAGE=true bundle exec rspec
+
+# Run RuboCop
+bundle exec rubocop
+
+# Run security audit
+bundle exec bundle audit check --update
+
+# Generate documentation
+bundle exec yard doc
+```
+
+### Release Process
+
+The gem uses automated CI/CD workflows:
+
+- **CI**: Automatically runs tests, linting, and security checks on every push and PR
+- **Release**: Supports both automatic releases (on GitHub release creation) and manual releases via workflow dispatch
+- **Documentation**: Automatically deploys API documentation to GitHub Pages
+
+To perform a release:
+
+1. **Dry Run**: Test the release process without publishing
+
+   ```bash
+   # Via GitHub Actions UI: Run "Release" workflow with dry_run=true
+   ```
+
+2. **Create Release**:
+
+   ```bash
+   # Update version in lib/whodunit/version.rb
+   # Commit and push changes
+   # Create a GitHub release via UI or CLI
+   gh release create v0.1.0 --title "Release v0.1.0" --notes "Release notes here"
+   ```
+
+3. **Manual Release** (if needed):
+   ```bash
+   # Via GitHub Actions UI: Run "Release" workflow with dry_run=false
+   ```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/kanutocd/whodunit.
+
+### Development Workflow
+
+1. Fork the repository
+2. Create a feature branch (`git checkout -b feature/amazing-feature`)
+3. Make your changes
+4. Add tests for new functionality
+5. Ensure all tests pass (`bundle exec rspec`)
+6. Run RuboCop and fix any style issues (`bundle exec rubocop`)
+7. Update documentation if needed
+8. Commit your changes (`git commit -am 'Add amazing feature'`)
+9. Push to the branch (`git push origin feature/amazing-feature`)
+10. Open a Pull Request
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).

data/Rakefile

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+# Load YARD tasks
+begin
+  require "yard"
+  YARD::Rake::YardocTask.new do |t|
+    t.files = ["lib/**/*.rb"]
+    t.options = %w[--output-dir doc --markup markdown]
+  end
+rescue LoadError
+  # YARD not available
+end
+
+task default: :spec

data/gemfiles/rails_7_2.gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Rails 7.2 testing
+gem "activerecord", "~> 7.2.0"
+gem "activesupport", "~> 7.2.0"
+
+# Specify your gem's dependencies in whodunit.gemspec
+gemspec path: "../"
+
+gem "irb"
+gem "rake", "~> 13.0"
+
+gem "rspec", "~> 3.0"

data/gemfiles/rails_8_2.gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Rails 8.0.2 testing
+gem "activerecord", "~> 8.0.0"
+gem "activesupport", "~> 8.0.0"
+
+# Specify your gem's dependencies in whodunit.gemspec
+gemspec path: "../"
+
+gem "irb"
+gem "rake", "~> 13.0"
+
+gem "rspec", "~> 3.0"

data/gemfiles/rails_edge.gemfile

@@ -0,0 +1,15 @@
+# frozen_string_literal: true
+
+source "https://rubygems.org"
+
+# Rails edge testing
+gem "activerecord", git: "https://github.com/rails/rails.git"
+gem "activesupport", git: "https://github.com/rails/rails.git"
+
+# Specify your gem's dependencies in whodunit.gemspec
+gemspec path: "../"
+
+gem "irb"
+gem "rake", "~> 13.0"
+
+gem "rspec", "~> 3.0"

data/lib/whodunit/controller_methods.rb

@@ -0,0 +1,196 @@
+# frozen_string_literal: true
+
+module Whodunit
+  # Controller integration for automatic user setting.
+  #
+  # This module provides seamless integration with Rails controllers by automatically
+  # setting and resetting the current user context for auditing purposes. It includes
+  # methods for manual user management and supports various user detection patterns.
+  #
+  # @example Automatic integration (via Railtie)
+  #   # This module is automatically included in ActionController::Base
+  #   class PostsController < ApplicationController
+  #     # Whodunit automatically tracks current_user for all actions
+  #     def create
+  #       @post = Post.create(params[:post])
+  #       # @post.creator_id is automatically set to current_user.id
+  #     end
+  #   end
+  #
+  # @example Manual user setting
+  #   class PostsController < ApplicationController
+  #     def admin_action
+  #       with_whodunit_user(User.admin) do
+  #         # Actions here will be tracked as performed by admin user
+  #         Post.create(title: "Admin Post")
+  #       end
+  #     end
+  #   end
+  #
+  # @example Skipping whodunit for specific actions
+  #   class PostsController < ApplicationController
+  #     skip_whodunit_for :index, :show
+  #     # or
+  #     whodunit_only_for :create, :update, :destroy
+  #   end
+  #
+  # @since 0.1.0
+  module ControllerMethods
+    extend ActiveSupport::Concern
+
+    included do
+      # Set up callbacks only for controllers that have user authentication
+      # Only if Rails controller methods are available
+      if respond_to?(:before_action) && respond_to?(:after_action)
+        before_action :set_whodunit_user, if: :whodunit_user_available?
+        after_action :reset_whodunit_user
+      end
+    end
+
+    # Set the current user for whodunit tracking.
+    #
+    # This method is automatically called as a before_action in controllers.
+    # Can also be called manually to set a specific user context.
+    #
+    # @param user [Object, nil] the user object or user ID to set
+    #   If nil, attempts to detect user via current_whodunit_user
+    # @return [void]
+    # @example Manual usage
+    #   set_whodunit_user(User.find(123))
+    #   set_whodunit_user(nil)  # Uses current_whodunit_user detection
+    def set_whodunit_user(user = nil)
+      user ||= current_whodunit_user
+      Whodunit::Current.user = user
+    end
+
+    # Reset the current user context.
+    #
+    # This method is automatically called as an after_action in controllers
+    # to ensure proper cleanup between requests.
+    #
+    # @return [void]
+    def reset_whodunit_user
+      Whodunit::Current.reset
+    end
+
+    # Detect the current user for auditing.
+    #
+    # This method tries multiple strategies to find the current user:
+    # 1. current_user method (most common Rails pattern)
+    # 2. @current_user instance variable
+    # 3. Other common authentication method names
+    #
+    # Override this method in your controller to customize user detection.
+    #
+    # @return [Object, nil] the current user object or nil if none found
+    # @example Custom user detection
+    #   def current_whodunit_user
+    #     # Custom logic for finding user
+    #     session[:admin_user] || super
+    #   end
+    def current_whodunit_user
+      return current_user if respond_to?(:current_user) && current_user
+      return @current_user if defined?(@current_user) && @current_user
+
+      # Try other common patterns
+      user_methods = %i[
+        current_user current_account current_admin
+        signed_in_user authenticated_user
+      ]
+
+      user_methods.each do |method|
+        return send(method) if respond_to?(method, true) && send(method)
+      end
+
+      nil
+    end
+
+    # Check if a user is available for stamping.
+    #
+    # Used internally by callbacks to determine if user tracking should occur.
+    #
+    # @return [Boolean] true if a user is available
+    def whodunit_user_available?
+      current_whodunit_user.present?
+    end
+
+    # Temporarily set a different user for a block of code.
+    #
+    # Useful for admin actions or background jobs that need to run
+    # as a specific user. Automatically restores the previous user context.
+    #
+    # @param user [Object] the user object to set temporarily
+    # @yield the block to execute with the temporary user
+    # @return [Object] the return value of the block
+    # @example
+    #   with_whodunit_user(admin_user) do
+    #     Post.create(title: "Admin post")
+    #   end
+    def with_whodunit_user(user)
+      previous_user = Whodunit::Current.user
+      begin
+        Whodunit::Current.user = user
+        yield
+      ensure
+        Whodunit::Current.user = previous_user
+      end
+    end
+
+    # Temporarily disable user tracking for a block of code.
+    #
+    # Useful for system operations or bulk imports where user tracking
+    # is not desired.
+    #
+    # @yield the block to execute without user tracking
+    # @return [Object] the return value of the block
+    # @example
+    #   without_whodunit_user do
+    #     Post.bulk_import(data)  # No creator_id will be set
+    #   end
+    def without_whodunit_user(&block)
+      with_whodunit_user(nil, &block)
+    end
+
+    class_methods do
+      # Skip whodunit tracking for specific controller actions.
+      #
+      # Disables automatic user tracking for the specified actions.
+      # Useful for read-only actions where auditing is not needed.
+      #
+      # @param actions [Array<Symbol>] the action names to skip
+      # @return [void]
+      # @example
+      #   class PostsController < ApplicationController
+      #     skip_whodunit_for :index, :show
+      #   end
+      def skip_whodunit_for(*actions)
+        return unless respond_to?(:skip_before_action) && respond_to?(:skip_after_action)
+
+        skip_before_action :set_whodunit_user, only: actions
+        skip_after_action :reset_whodunit_user, only: actions
+      end
+
+      # Enable whodunit tracking only for specific controller actions.
+      #
+      # Disables automatic tracking for all actions, then re-enables it
+      # only for the specified actions. Useful for controllers where
+      # only certain actions need auditing.
+      #
+      # @param actions [Array<Symbol>] the action names to enable tracking for
+      # @return [void]
+      # @example
+      #   class PostsController < ApplicationController
+      #     whodunit_only_for :create, :update, :destroy
+      #   end
+      def whodunit_only_for(*actions)
+        return unless respond_to?(:skip_before_action) && respond_to?(:before_action) && respond_to?(:after_action)
+
+        skip_before_action :set_whodunit_user
+        skip_after_action :reset_whodunit_user
+
+        before_action :set_whodunit_user, only: actions, if: :whodunit_user_available?
+        after_action :reset_whodunit_user, only: actions
+      end
+    end
+  end
+end