rake_audit 0.1.0

data/app/views/rake_audit/executions/show.html.erb

@@ -0,0 +1,46 @@
+<h1>Execution #<%= @execution.id %></h1>
+
+<p><%= link_to "← Back to executions", executions_path %></p>
+
+<section class="section">
+  <h2>Task Info</h2>
+  <dl>
+    <dt>Task Name</dt><dd><%= @execution.task_name %></dd>
+    <dt>Status</dt>
+    <dd class="status-<%= @execution.status %>"><%= @execution.status %></dd>
+  </dl>
+</section>
+
+<section class="section">
+  <h2>Arguments</h2>
+  <pre><%= JSON.pretty_generate(@execution.arguments) if @execution.arguments.present? %></pre>
+</section>
+
+<section class="section">
+  <h2>Execution Info</h2>
+  <dl>
+    <dt>Started At</dt><dd><%= @execution.started_at %></dd>
+    <dt>Finished At</dt><dd><%= @execution.finished_at %></dd>
+    <dt>Duration (ms)</dt><dd><%= @execution.duration_ms %></dd>
+  </dl>
+</section>
+
+<% unless @execution.status == "success" %>
+  <section class="section">
+    <h2>Error Info</h2>
+    <dl>
+      <dt>Error Class</dt><dd><%= @execution.error_class %></dd>
+      <dt>Error Message</dt><dd><%= @execution.error_message %></dd>
+    </dl>
+  </section>
+<% end %>
+
+<section class="section">
+  <h2>Environment Info</h2>
+  <dl>
+    <dt>Hostname</dt><dd><%= @execution.hostname %></dd>
+    <dt>PID</dt><dd><%= @execution.pid %></dd>
+    <dt>Ruby Version</dt><dd><%= @execution.ruby_version %></dd>
+    <dt>Rails Env</dt><dd><%= @execution.rails_env %></dd>
+  </dl>
+</section>

data/config/routes.rb

@@ -0,0 +1,13 @@
+# frozen_string_literal: true
+
+# Routes for the mounted RakeAudit Engine.
+#
+# Because the Engine isolates its namespace, these paths live beneath the mount
+# point the host application chooses (conventionally +/rake_audit+). The root
+# points at the execution list so the mount point itself is useful; the
+# dashboard and the execution +index+/+show+ actions round out the UI.
+RakeAudit::Engine.routes.draw do
+  root to: 'executions#index'
+  get 'dashboard', to: 'dashboard#index'
+  resources :executions, only: %i[index show]
+end

data/db/migrate/20260531120000_create_rake_task_executions.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+# Creates the +rake_task_executions+ table that backs
+# {RakeAudit::TaskExecution}.
+#
+# The +arguments+ column type is chosen per database so the same migration runs
+# on PostgreSQL, MySQL, and SQLite: +jsonb+ on PostgreSQL, +json+ on MySQL, and
+# +text+ everywhere else (SQLite stores the serialized JSON as text). All six
+# indexes from the specification are created: four single-column lookups plus
+# two composite indexes that match the Web UI's primary query patterns.
+class CreateRakeTaskExecutions < ActiveRecord::Migration[6.1]
+  def change
+    create_table :rake_task_executions do |t|
+      t.string :task_name, null: false, limit: 255
+      t.column :arguments, arguments_column_type, null: true
+      t.datetime :started_at, null: false
+      t.datetime :finished_at, null: false
+      t.bigint :duration_ms, null: true
+      t.string :status, null: false, limit: 20
+      t.string :error_class, null: true, limit: 255
+      t.text :error_message, null: true
+      t.string :hostname, null: true, limit: 255
+      t.integer :pid, null: true
+      t.string :ruby_version, null: true, limit: 50
+      t.string :rails_env, null: true, limit: 50
+
+      t.timestamps
+    end
+
+    add_audit_indexes
+  end
+
+  private
+
+  # Add the four single-column and two composite indexes that back the audit
+  # table's lookup and Web UI query patterns.
+  #
+  # @return [void]
+  def add_audit_indexes
+    add_index :rake_task_executions, :task_name
+    add_index :rake_task_executions, :status
+    add_index :rake_task_executions, :started_at
+    add_index :rake_task_executions, :hostname
+    add_index :rake_task_executions, %i[task_name started_at]
+    add_index :rake_task_executions, %i[status started_at]
+  end
+
+  # Pick a JSON-capable column type the current database supports, falling back
+  # to +text+ (used by SQLite) so the migration is portable across backends.
+  #
+  # @return [Symbol]
+  def arguments_column_type
+    adapter = connection.adapter_name.downcase
+    if adapter.include?('postgresql')
+      :jsonb
+    elsif adapter.include?('mysql')
+      :json
+    else
+      :text
+    end
+  end
+end

data/lib/generators/rake_audit/install_generator.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+require 'rails/generators'
+require 'rails/generators/active_record'
+
+module RakeAudit
+  module Generators
+    # Scaffolds RakeAudit into a host Rails application.
+    #
+    #   rails generate rake_audit:install
+    #
+    # Running the generator copies a commented-out initializer to
+    # +config/initializers/rake_audit.rb+ and writes a timestamped migration to
+    # +db/migrate+ that creates the +rake_task_executions+ table. The migration
+    # is produced through +migration_template+ so the host's schema version and
+    # migration numbering are respected.
+    class InstallGenerator < ::Rails::Generators::Base
+      include ::ActiveRecord::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Creates the RakeAudit initializer and the rake_task_executions migration.'
+
+      # Copy the pre-filled, fully commented initializer into the host app.
+      #
+      # @return [void]
+      def create_initializer
+        template 'initializer.rb', 'config/initializers/rake_audit.rb'
+      end
+
+      # Generate the timestamped migration that creates the audit table.
+      #
+      # @return [void]
+      def create_migration_file
+        migration_template(
+          'create_rake_task_executions.rb',
+          'db/migrate/create_rake_task_executions.rb'
+        )
+      end
+    end
+  end
+end

data/lib/generators/rake_audit/templates/create_rake_task_executions.rb

@@ -0,0 +1,55 @@
+# frozen_string_literal: true
+
+# Creates the +rake_task_executions+ table that backs
+# RakeAudit::TaskExecution.
+#
+# The +arguments+ column type is chosen per database so the same migration runs
+# on PostgreSQL, MySQL, and SQLite: +jsonb+ on PostgreSQL, +json+ on MySQL, and
+# +text+ everywhere else (SQLite stores the serialized JSON as text).
+class CreateRakeTaskExecutions < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+    create_table :rake_task_executions do |t|
+      t.string :task_name, null: false, limit: 255
+      t.column :arguments, arguments_column_type, null: true
+      t.datetime :started_at, null: false
+      t.datetime :finished_at, null: false
+      t.bigint :duration_ms, null: true
+      t.string :status, null: false, limit: 20
+      t.string :error_class, null: true, limit: 255
+      t.text :error_message, null: true
+      t.string :hostname, null: true, limit: 255
+      t.integer :pid, null: true
+      t.string :ruby_version, null: true, limit: 50
+      t.string :rails_env, null: true, limit: 50
+
+      t.timestamps
+    end
+
+    add_audit_indexes
+  end
+
+  private
+
+  # Add the four single-column and two composite indexes.
+  def add_audit_indexes
+    add_index :rake_task_executions, :task_name
+    add_index :rake_task_executions, :status
+    add_index :rake_task_executions, :started_at
+    add_index :rake_task_executions, :hostname
+    add_index :rake_task_executions, %i[task_name started_at]
+    add_index :rake_task_executions, %i[status started_at]
+  end
+
+  # Pick a JSON-capable column type the current database supports, falling back
+  # to +text+ (used by SQLite) so the migration is portable across backends.
+  def arguments_column_type
+    adapter = connection.adapter_name.downcase
+    if adapter.include?('postgresql')
+      :jsonb
+    elsif adapter.include?('mysql')
+      :json
+    else
+      :text
+    end
+  end
+end

data/lib/generators/rake_audit/templates/initializer.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+# RakeAudit configuration.
+#
+# Every option below is shown with its default and left commented out. Uncomment
+# and edit the lines you want to override. At minimum, set an adapter to enable
+# recording — without one, RakeAudit loads but records nothing.
+RakeAudit.configure do |config|
+  # config.adapter = RakeAudit::Adapters::ActiveRecordAdapter.new
+  # config.logger  = Rails.logger
+  # config.capture_hostname     = true
+  # config.capture_pid          = true
+  # config.capture_ruby_version = true
+  # config.capture_rails_env    = true
+  # config.web_ui_enabled       = true
+  # config.authenticate_with    = ->(controller) { controller.authenticate_admin! }
+end

data/lib/rake_audit/adapters/active_record_adapter.rb

@@ -0,0 +1,73 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative '../record_not_found'
+
+module RakeAudit
+  module Adapters
+    # Persists and queries TaskExecutionRecord instances via ActiveRecord.
+    class ActiveRecordAdapter < Base
+      EXACT_FILTERS = %i[task_name status hostname rails_env].freeze
+      private_constant :EXACT_FILTERS
+
+      # Create a TaskExecution row from the given record.
+      #
+      # @param record [TaskExecutionRecord]
+      def save(record)
+        RakeAudit::TaskExecution.create!(record.to_h)
+      end
+
+      # @param filters [Hash] pre-validated non-blank filter values.
+      # @param page [Integer, String, nil]
+      # @param per_page [Integer]
+      # @return [ActiveRecord::Relation] kaminari-paginated relation.
+      def query(filters: {}, page: nil, per_page: 25)
+        scope = RakeAudit::TaskExecution.order(started_at: :desc)
+
+        EXACT_FILTERS.each do |col|
+          scope = scope.where(col => filters[col]) if filters.key?(col)
+        end
+        scope = scope.where(started_at: filters[:from]..) if filters.key?(:from)
+        scope = scope.where(started_at: ..filters[:to])   if filters.key?(:to)
+
+        scope.page(page).per(per_page)
+      end
+
+      # @param id [Integer, String]
+      # @return [RakeAudit::TaskExecution]
+      # @raise [RakeAudit::RecordNotFound]
+      def find(id)
+        RakeAudit::TaskExecution.find(id)
+      rescue ActiveRecord::RecordNotFound
+        raise RakeAudit::RecordNotFound, "Couldn't find execution with id=#{id}"
+      end
+
+      # @return [Integer]
+      def count
+        RakeAudit::TaskExecution.count
+      end
+
+      # @param status [String]
+      # @return [Integer]
+      def count_by_status(status)
+        RakeAudit::TaskExecution.where(status: status).count
+      end
+
+      # @return [Float, nil]
+      def average_duration_ms
+        RakeAudit::TaskExecution.average(:duration_ms)
+      end
+
+      # @param limit [Integer]
+      # @return [Array<Array(String, Integer)>]
+      def top_failed_tasks(limit: 10)
+        RakeAudit::TaskExecution
+          .where(status: 'failure')
+          .group(:task_name)
+          .count
+          .sort_by { |_, c| -c }
+          .first(limit)
+      end
+    end
+  end
+end

data/lib/rake_audit/adapters/base.rb

@@ -0,0 +1,94 @@
+# frozen_string_literal: true
+
+module RakeAudit
+  module Adapters
+    # Abstract storage adapter defining the full persistence and query contract.
+    #
+    # Every concrete adapter must implement +#save+. Adapters that back the Web
+    # UI must also implement the six query methods below; the default
+    # implementations raise +NotImplementedError+ so omissions surface loudly.
+    class Base
+      # Persist a TaskExecutionRecord.
+      #
+      # @param record [TaskExecutionRecord] the record to save.
+      # @raise [NotImplementedError] when not overridden.
+      def save(record)
+        raise NotImplementedError, "#{self.class}#save is not implemented"
+      end
+
+      # Return a kaminari-paginated, filtered, newest-first collection.
+      #
+      # @param filters [Hash] any subset of: +:task_name+, +:status+,
+      #   +:hostname+, +:rails_env+, +:from+, +:to+ (all pre-validated,
+      #   non-blank values only — blank keys are never present).
+      # @param page [Integer, String, nil] 1-based page number.
+      # @param per_page [Integer] records per page.
+      # @raise [NotImplementedError] when not overridden.
+      def query(filters: {}, page: nil, per_page: 25)
+        raise NotImplementedError, "#{self.class}#query is not implemented"
+      end
+
+      # Return a single execution record by ID.
+      #
+      # @param id [String, Integer] adapter-specific identifier.
+      # @raise [RakeAudit::RecordNotFound] when no record matches.
+      # @raise [NotImplementedError] when not overridden.
+      def find(id)
+        raise NotImplementedError, "#{self.class}#find is not implemented"
+      end
+
+      # Total number of stored executions.
+      #
+      # @return [Integer]
+      # @raise [NotImplementedError] when not overridden.
+      def count
+        raise NotImplementedError, "#{self.class}#count is not implemented"
+      end
+
+      # Number of executions whose +status+ equals +status+.
+      #
+      # @param status [String] e.g. <tt>"success"</tt> or <tt>"failure"</tt>.
+      # @return [Integer]
+      # @raise [NotImplementedError] when not overridden.
+      def count_by_status(status)
+        raise NotImplementedError, "#{self.class}#count_by_status is not implemented"
+      end
+
+      # Mean +duration_ms+ across all stored executions, or +nil+ when empty.
+      #
+      # @return [Float, nil]
+      # @raise [NotImplementedError] when not overridden.
+      def average_duration_ms
+        raise NotImplementedError, "#{self.class}#average_duration_ms is not implemented"
+      end
+
+      # The +limit+ task names with the most failures, ordered descending.
+      #
+      # @param limit [Integer]
+      # @return [Array<Array(String, Integer)>] e.g. +[["db:migrate", 5], ...]+
+      # @raise [NotImplementedError] when not overridden.
+      def top_failed_tasks(limit: 10)
+        raise NotImplementedError, "#{self.class}#top_failed_tasks is not implemented"
+      end
+
+      # All five dashboard metrics in a single call.
+      #
+      # The default implementation delegates to the five individual methods, which
+      # is efficient for SQL-backed adapters (five fast queries). Adapters whose
+      # individual methods are expensive (e.g. Redis, which reads the full list
+      # per call) should override this to compute everything in one pass.
+      #
+      # @return [Hash] with keys +:total+, +:success_count+, +:failure_count+,
+      #   +:average_duration_ms+, +:top_failed_tasks+.
+      def stats
+        {
+          total: count,
+          success_count: count_by_status('success'),
+          failure_count: count_by_status('failure'),
+          average_duration_ms: average_duration_ms,
+          top_failed_tasks: top_failed_tasks
+        }
+      end
+    end
+  end
+end

data/lib/rake_audit/adapters/execution_record.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+module RakeAudit
+  module Adapters
+    # Read-side value object returned by non-ActiveRecord adapters.
+    #
+    # Carries every field the Web UI views access plus an +id+ and +to_param+
+    # so Rails route helpers (+execution_path(record)+) work without AR.
+    ExecutionRecord = Struct.new(
+      :id, :task_name, :arguments, :started_at, :finished_at,
+      :duration_ms, :status, :error_class, :error_message,
+      :hostname, :pid, :ruby_version, :rails_env,
+      keyword_init: true
+    ) do
+      def to_param
+        id.to_s
+      end
+    end
+  end
+end

data/lib/rake_audit/adapters/mongo_adapter.rb

@@ -0,0 +1,137 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'execution_record'
+require_relative '../record_not_found'
+
+module RakeAudit
+  module Adapters
+    # Persists and queries TaskExecutionRecord instances via MongoDB.
+    #
+    # Uses the MongoDB Ruby driver directly. Documents are stored in the
+    # +rake_task_executions+ collection and Mongo's native +_id+ (ObjectId) is
+    # used as the record identifier for Web UI links.
+    class MongoAdapter < Base
+      # @param client [Mongo::Client] a connected MongoDB client instance.
+      def initialize(client:)
+        super()
+        @client = client
+      end
+
+      # Insert the record into the executions collection.
+      #
+      # @param record [TaskExecutionRecord]
+      def save(record)
+        collection.insert_one(record.to_h)
+      end
+
+      # @param filters [Hash] pre-validated non-blank filter values.
+      # @param page [Integer, String, nil]
+      # @param per_page [Integer]
+      # @return [Kaminari::PaginatableArray]
+      def query(filters: {}, page: nil, per_page: 25)
+        require 'kaminari'
+        filter      = build_filter(filters)
+        total       = collection.count_documents(filter)
+        current     = [page.to_i, 1].max
+        cursor      = collection.find(filter)
+                                .sort(started_at: -1)
+                                .skip((current - 1) * per_page)
+                                .limit(per_page)
+
+        records = cursor.map { |doc| to_execution_record(doc) }
+        Kaminari
+          .paginate_array(records, total_count: total)
+          .page(current)
+          .per(per_page)
+      end
+
+      # @param id [String] string representation of a Mongo ObjectId.
+      # @return [RakeAudit::Adapters::ExecutionRecord]
+      # @raise [RakeAudit::RecordNotFound]
+      def find(id)
+        # Skip the require when BSON is already defined (e.g. stubbed in tests).
+        require 'bson' unless defined?(BSON)
+        object_id = BSON::ObjectId.from_string(id.to_s)
+        doc = collection.find(_id: object_id).first
+        raise RakeAudit::RecordNotFound, "Couldn't find execution with id=#{id}" unless doc
+
+        to_execution_record(doc)
+      rescue ArgumentError
+        # BSON::ObjectId::Invalid inherits from ArgumentError — invalid id string.
+        raise RakeAudit::RecordNotFound, "Couldn't find execution with id=#{id}"
+      end
+
+      # @return [Integer]
+      def count
+        collection.count_documents({})
+      end
+
+      # @param status [String]
+      # @return [Integer]
+      def count_by_status(status)
+        collection.count_documents('status' => status)
+      end
+
+      # @return [Float, nil]
+      def average_duration_ms
+        result = collection.aggregate([
+                                        { '$group' => { '_id' => nil, 'avg' => { '$avg' => '$duration_ms' } } }
+                                      ]).first
+        result ? result['avg'] : nil
+      end
+
+      # @param limit [Integer]
+      # @return [Array<Array(String, Integer)>]
+      def top_failed_tasks(limit: 10)
+        collection.aggregate([
+                               { '$match' => { 'status' => 'failure' } },
+                               { '$group'  => { '_id' => '$task_name', 'count' => { '$sum' => 1 } } },
+                               { '$sort'   => { 'count' => -1 } },
+                               { '$limit'  => limit }
+                             ]).map { |doc| [doc['_id'], doc['count']] }
+      end
+
+      private
+
+      def collection
+        @client['rake_task_executions']
+      end
+
+      def build_filter(filters)
+        filter = {}
+
+        %i[task_name status hostname rails_env].each do |col|
+          filter[col.to_s] = filters[col] if filters.key?(col)
+        end
+
+        if filters.key?(:from) || filters.key?(:to)
+          range = {}
+          range['$gte'] = filters[:from].to_s if filters.key?(:from)
+          range['$lte'] = filters[:to].to_s   if filters.key?(:to)
+          filter['started_at'] = range
+        end
+
+        filter
+      end
+
+      def to_execution_record(doc)
+        RakeAudit::Adapters::ExecutionRecord.new(
+          id: doc['_id']&.to_s,
+          task_name: doc['task_name'],
+          arguments: doc['arguments'],
+          started_at: doc['started_at'],
+          finished_at: doc['finished_at'],
+          duration_ms: doc['duration_ms'],
+          status: doc['status'],
+          error_class: doc['error_class'],
+          error_message: doc['error_message'],
+          hostname: doc['hostname'],
+          pid: doc['pid'],
+          ruby_version: doc['ruby_version'],
+          rails_env: doc['rails_env']
+        )
+      end
+    end
+  end
+end