action-audit 1.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 15ebeba499703a1b1ac0eca27102c710d6ca91595f5b85faed6214be8f242013
+  data.tar.gz: a76826e7286f9226dafe4c6145ea426393c2dc2152a5d2602400ff32e7665c71
+SHA512:
+  metadata.gz: e643aa00da95ca4a38f5e2ec9ec2d14a7b4239c6be6be2289c664dcf35d742b1917f21c9f24854a3835d8cd4087f3fd98a6272283c43410d2aa0195f2f89ef9b
+  data.tar.gz: a0911417abf68c6084e21a675d0e0b27ea5cf6b2898dd79eb415a9d9e70b42413635f5ea9673e13a78f7a19a211aed596b365f8cc818d40cf95bf3227e23186e

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,17 @@
+inherit_gem:
+  rubocop-rails-omakase: rubocop.yml
+
+AllCops:
+  NewCops: enable
+  TargetRubyVersion: 3.1
+
+# Gem-specific customizations
+Metrics/BlockLength:
+  Exclude:
+    - 'spec/**/*'
+    - '*.gemspec'
+
+Style/Documentation:
+  Exclude:
+    - 'spec/**/*'
+    - 'lib/action_audit/version.rb'

data/CHANGELOG.md

@@ -0,0 +1,29 @@
+## [Unreleased]
+
+## [1.0.0] - 2025-10-07
+
+### Added
+- Initial release of ActionAudit gem
+- Automatic auditing of controller actions via `after_action` callback
+- YAML-based audit message configuration with `config/audit.yml` files
+- Multi-engine support - automatically loads audit configurations from all Rails engines
+- Parameter interpolation in audit messages using controller params (e.g., `%{id}`, `%{email}`)
+- Customizable log formatting via `ActionAudit.log_formatter`
+- Customizable log tagging via `ActionAudit.log_tag`
+- Rails engine integration for automatic configuration loading
+- Comprehensive test suite with RSpec
+- Rails generator for easy installation (`rails generate action_audit:install`)
+- Full documentation with examples and usage patterns
+
+### Features
+- **ActiveSupport::Concern** integration for easy inclusion in controllers
+- **Nested controller path support** (e.g., `Manage::AccountsController` → `manage/accounts`)
+- **Error handling** for interpolation failures with graceful fallbacks
+- **Request context preservation** including Rails request_id when available
+- **Development mode support** with automatic configuration reloading
+- **Flexible message registry** similar to I18n for consistent audit message management
+
+### Examples
+- Sample audit.yml configurations for various use cases
+- Custom log formatter examples with timestamps and user information
+- Multi-engine setup examples

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,25 @@
+# Code of Conduct
+
+## Our Commitment
+
+We are committed to providing a friendly, safe, and welcoming environment for all contributors and users of this project.
+
+## Expected Behavior
+
+* Be respectful and inclusive in your language and actions
+* Accept constructive feedback gracefully
+* Focus on what is best for the community and the project
+* Show empathy towards other community members
+
+## Unacceptable Behavior
+
+* Harassment, discrimination, or abusive language of any kind
+* Trolling, insulting comments, or personal attacks
+* Publishing private information without permission
+* Any conduct that could reasonably be considered inappropriate in a professional setting
+
+## Enforcement
+
+Instances of unacceptable behavior may be reported by contacting the project maintainer. All complaints will be reviewed and investigated fairly and promptly.
+
+Project maintainers have the right and responsibility to remove, edit, or reject comments, commits, code, issues, and other contributions that are not aligned with this Code of Conduct.

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vinay Uttam Vemparala
+
+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,232 @@
+# ActionAudit
+
+A Rails gem that provides automatic auditing of controller actions across multiple Rails engines. ActionAudit works similar to `I18n` by loading audit messages from YAML files, but focuses on logging controller actions with customizable formatting and tagging while preserving Rails request context.
+
+## Features
+
+- **Automatic auditing**: Hooks into controller actions via `after_action`
+- **YAML-based configuration**: Load audit messages from `config/audit.yml` files
+- **Multi-engine support**: Automatically loads configurations from all Rails engines
+- **Customizable formatting**: Configure custom log formatters and tags
+- **Parameter interpolation**: Support for dynamic message interpolation using controller parameters
+- **Rails integration**: Preserves request context including `request_id`
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'action_audit'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install action_audit
+
+## Usage
+
+### 1. Include in Controllers
+
+Include the `ActionAudit` module in any controller you want to audit:
+
+```ruby
+class Manage::AccountsController < ApplicationController
+  include ActionAudit
+
+  def create
+    @account = Account.create!(account_params)
+    # audit_request is automatically called after this action
+  end
+
+  def update
+    @account = Account.find(params[:id])
+    @account.update!(account_params)
+  end
+
+  private
+
+  def account_params
+    params.require(:account).permit(:name, :email)
+  end
+end
+```
+
+### 2. Configure Audit Messages
+
+Create a `config/audit.yml` file in your Rails application or engine:
+
+```yaml
+# config/audit.yml
+manage:
+  accounts:
+    create: "Created account %{id}"
+    update: "Updated account %{id} with %{name}"
+    destroy: "Deleted account %{id}"
+  users:
+    invite: "Invited user %{email}"
+    create: "Created user %{email}"
+
+sessions:
+  create: "User logged in with email %{email}"
+  destroy: "User logged out"
+
+posts:
+  create: "Created post '%{title}'"
+  update: "Updated post %{id}"
+  publish: "Published post %{id}"
+```
+
+### 3. Customize Logging (Optional)
+
+Create an initializer to customize the logging behavior:
+
+```ruby
+# config/initializers/action_audit.rb
+
+# Add a custom tag to all audit logs
+ActionAudit.log_tag = "AUDIT"
+
+# Customize the log format
+ActionAudit.log_formatter = lambda do |controller, action, message|
+  user_info = defined?(current_user) && current_user ? "User: #{current_user.email}" : "User: anonymous"
+  "[#{Time.current.iso8601}] #{controller}/#{action} | #{message} | #{user_info}"
+end
+```
+
+### 4. Multi-Engine Support
+
+ActionAudit automatically loads `config/audit.yml` files from:
+- Your main Rails application
+- All mounted Rails engines
+
+Each engine can have its own audit configuration that will be merged together.
+
+## Configuration Options
+
+### Log Formatter
+
+Customize how log messages are formatted:
+
+```ruby
+# Simple formatter
+ActionAudit.log_formatter = ->(controller, action, msg) do
+  "AUDIT: #{controller}/#{action} - #{msg}"
+end
+
+# Complex formatter with timestamp and user info
+ActionAudit.log_formatter = lambda do |controller, action, message|
+  timestamp = Time.current.strftime("%Y-%m-%d %H:%M:%S")
+  "[#{timestamp}] AUDIT: #{controller}/#{action} - #{message}"
+end
+```
+
+### Log Tag
+
+Add a consistent tag to all audit logs:
+
+```ruby
+ActionAudit.log_tag = "AUDIT"
+# or
+ActionAudit.log_tag = "APP_AUDIT"
+```
+
+## Message Interpolation
+
+Audit messages support parameter interpolation using controller params:
+
+```yaml
+# audit.yml
+accounts:
+  create: "Created account %{id} for %{name}"
+  update: "Updated account %{id} - changed %{changed_fields}"
+```
+
+```ruby
+# In your controller
+def create
+  @account = Account.create!(name: params[:name])
+  # Will log: "Created account 123 for Acme Corp"
+  # Uses params[:id] and params[:name] for interpolation
+end
+```
+
+## Example Log Output
+
+### Default Format
+```
+manage/accounts/create - Created account 123
+manage/accounts/update - Updated account 123 with Acme Corp
+sessions/create - User logged in with email john@example.com
+```
+
+### With Custom Formatter and Tag
+```
+[AUDIT] [2025-01-15T10:30:00Z] manage/accounts/create | Created account 123 | User: john@example.com
+[AUDIT] [2025-01-15T10:31:00Z] manage/accounts/update | Updated account 123 with Acme Corp | User: john@example.com
+[AUDIT] [2025-01-15T10:32:00Z] sessions/destroy | User logged out | User: john@example.com
+```
+
+## API Reference
+
+### ActionAudit Module
+
+When included in a controller, automatically adds:
+- `after_action :audit_request` - Hooks into action completion
+- `audit_request` - Private method that performs the logging
+- `interpolate_message` - Private method for parameter interpolation
+
+### ActionAudit.log_formatter
+
+A `Proc` that receives `(controller_path, action_name, interpolated_message)` and returns a formatted string.
+
+**Default**: `"#{controller_path}/#{action_name} - #{interpolated_message}"`
+
+### ActionAudit.log_tag
+
+A string tag to be used with `Rails.logger.tagged()`.
+
+**Default**: `nil` (no tagging)
+
+### ActionAudit::AuditMessages
+
+Registry for audit messages with methods:
+- `.lookup(controller_path, action_name)` - Find a message
+- `.load_from_file(file_path)` - Load messages from YAML file
+- `.load_from_engines` - Load from all Rails engines
+- `.add_message(controller_path, action_name, message)` - Add a message programmatically
+- `.clear!` - Clear all messages
+
+## Documentation
+
+For comprehensive documentation, see the [docs](docs/) directory:
+
+- [Installation Guide](docs/installation.md) - Step-by-step setup instructions
+- [Configuration Guide](docs/configuration.md) - How to configure audit messages and logging
+- [Usage Guide](docs/usage.md) - How to use ActionAudit in your controllers
+- [Multi-Engine Setup](docs/multi-engine.md) - Using ActionAudit across Rails engines
+- [API Reference](docs/api-reference.md) - Complete API documentation
+- [Examples](docs/examples.md) - Real-world usage examples
+- [Troubleshooting](docs/troubleshooting.md) - Common issues and solutions
+- [Migration Guide](docs/migration.md) - Migrating from other audit solutions
+
+*Documentation generated by GitHub Copilot*
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+The project uses RuboCop Rails Omakase for code style. Run `bundle exec rubocop` to check style, or `bundle exec rake` to run both tests and RuboCop checks.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/[USERNAME]/action_audit. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/[USERNAME]/action_audit/blob/main/CODE_OF_CONDUCT.md).
+
+## Code of Conduct
+
+Everyone interacting in the ActionAudit project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/[USERNAME]/action_audit/blob/main/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/docs/README.md

@@ -0,0 +1,25 @@
+# ActionAudit Documentation
+
+Welcome to the ActionAudit gem documentation. This directory contains comprehensive guides on how to install, configure, and use ActionAudit in your Rails applications.
+
+## Documentation Structure
+
+- [**Installation Guide**](installation.md) - Step-by-step installation and setup
+- [**Configuration Guide**](configuration.md) - How to configure audit messages and logging
+- [**Usage Guide**](usage.md) - How to use ActionAudit in your controllers
+- [**Multi-Engine Setup**](multi-engine.md) - Using ActionAudit across multiple Rails engines
+- [**API Reference**](api-reference.md) - Complete API documentation
+- [**Examples**](examples.md) - Real-world usage examples
+- [**Troubleshooting**](troubleshooting.md) - Common issues and solutions
+- [**Migration Guide**](migration.md) - Migrating from other audit solutions
+
+## Quick Start
+
+For a quick overview, check out the [Installation Guide](installation.md) and [Usage Guide](usage.md).
+
+## Support
+
+If you encounter any issues or have questions, please:
+1. Check the [Troubleshooting Guide](troubleshooting.md)
+2. Review the [API Reference](api-reference.md)
+3. Open an issue on the [GitHub repository](https://github.com/vinayuttamvemparala/action_audit)