rake_audit 0.1.0

data/lib/rake_audit/adapters/redis_adapter.rb

@@ -0,0 +1,174 @@
+# frozen_string_literal: true
+
+require_relative 'base'
+require_relative 'execution_record'
+require_relative '../record_not_found'
+require 'json'
+require 'securerandom'
+
+module RakeAudit
+  module Adapters
+    # Persists and queries TaskExecutionRecord instances via Redis.
+    #
+    # Each record is serialized as JSON (with a generated UUID +id+ field) and
+    # prepended to the +rake_audit:executions+ list key via +LPUSH+. Query
+    # methods read the full list and filter/sort/paginate in Ruby, making this
+    # adapter suitable for low-to-moderate write volumes where a full DB is
+    # unavailable but basic Web UI introspection is still desired.
+    class RedisAdapter < Base # rubocop:disable Metrics/ClassLength
+      # @param client [Redis] a connected Redis client instance.
+      def initialize(client:)
+        super()
+        @client = client
+      end
+
+      # Push the serialized record onto the executions list.
+      # A UUID +id+ is generated and embedded so the Web UI can link to details.
+      #
+      # @param record [TaskExecutionRecord]
+      def save(record)
+        data = record.to_h.merge(id: SecureRandom.uuid)
+        @client.lpush('rake_audit:executions', data.to_json)
+      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'
+        records = filtered_and_sorted(filters)
+        total   = records.size
+        current = [page.to_i, 1].max
+        paged   = records.slice((current - 1) * per_page, per_page) || []
+
+        Kaminari
+          .paginate_array(paged.map { |r| to_execution_record(r) }, total_count: total)
+          .page(current)
+          .per(per_page)
+      end
+
+      # @param id [String] UUID stored at write time.
+      # @return [RakeAudit::Adapters::ExecutionRecord]
+      # @raise [RakeAudit::RecordNotFound]
+      def find(id)
+        raw = all_records.find { |r| r[:id].to_s == id.to_s }
+        raise RakeAudit::RecordNotFound, "Couldn't find execution with id=#{id}" unless raw
+
+        to_execution_record(raw)
+      end
+
+      # @return [Integer]
+      def count
+        all_records.size
+      end
+
+      # @param status [String]
+      # @return [Integer]
+      def count_by_status(status)
+        all_records.count { |r| r[:status].to_s == status }
+      end
+
+      # @return [Float, nil]
+      def average_duration_ms
+        records = all_records
+        return nil if records.empty?
+
+        records.sum { |r| r[:duration_ms].to_f } / records.size
+      end
+
+      # @param limit [Integer]
+      # @return [Array<Array(String, Integer)>]
+      def top_failed_tasks(limit: 10)
+        top_failed_from(all_records.select { |r| r[:status].to_s == 'failure' }, limit: limit)
+      end
+
+      # Single-pass override: reads the full Redis list once and derives all five
+      # dashboard metrics in memory, replacing the default five-separate-LRANGE
+      # implementation inherited from Base.
+      #
+      # @return [Hash]
+      def stats
+        records      = all_records
+        total        = records.size
+        failure_recs = records.select { |r| r[:status].to_s == 'failure' }
+
+        {
+          total: total,
+          success_count: records.count { |r| r[:status].to_s == 'success' },
+          failure_count: failure_recs.size,
+          average_duration_ms: avg_duration(records, total),
+          top_failed_tasks: top_failed_from(failure_recs)
+        }
+      end
+
+      private
+
+      def all_records
+        @client
+          .lrange('rake_audit:executions', 0, -1)
+          .map { |json| JSON.parse(json, symbolize_names: true) }
+      end
+
+      def avg_duration(records, total)
+        total.zero? ? nil : records.sum { |r| r[:duration_ms].to_f } / total
+      end
+
+      def top_failed_from(failure_records, limit: 10)
+        failure_records
+          .group_by { |r| r[:task_name].to_s }
+          .transform_values(&:size)
+          .sort_by { |_, c| -c }
+          .first(limit)
+          .map { |name, c| [name, c] }
+      end
+
+      def filtered_and_sorted(filters)
+        apply_date_range(apply_exact_filters(all_records, filters), filters)
+          .sort_by { |r| parse_time(r[:started_at]).to_i }
+          .reverse
+      end
+
+      def apply_exact_filters(records, filters)
+        %i[task_name status hostname rails_env].reduce(records) do |recs, col|
+          next recs unless filters.key?(col)
+
+          recs.select { |r| r[col].to_s == filters[col].to_s }
+        end
+      end
+
+      def apply_date_range(records, filters)
+        records = records.select { |r| parse_time(r[:started_at]) >= parse_time(filters[:from]) } if filters.key?(:from)
+        records = records.select { |r| parse_time(r[:started_at]) <= parse_time(filters[:to]) }   if filters.key?(:to)
+        records
+      end
+
+      def parse_time(value)
+        return Time.at(0) if value.nil?
+        return value if value.is_a?(Time)
+
+        Time.parse(value.to_s)
+      rescue ArgumentError
+        Time.at(0)
+      end
+
+      def to_execution_record(raw)
+        RakeAudit::Adapters::ExecutionRecord.new(
+          id: raw[:id]&.to_s,
+          task_name: raw[:task_name],
+          arguments: raw[:arguments],
+          started_at: raw[:started_at],
+          finished_at: raw[:finished_at],
+          duration_ms: raw[:duration_ms],
+          status: raw[:status],
+          error_class: raw[:error_class],
+          error_message: raw[:error_message],
+          hostname: raw[:hostname],
+          pid: raw[:pid],
+          ruby_version: raw[:ruby_version],
+          rails_env: raw[:rails_env]
+        )
+      end
+    end
+  end
+end

data/lib/rake_audit/builders/task_execution_record_builder.rb

@@ -0,0 +1,81 @@
+# frozen_string_literal: true
+
+require 'socket'
+
+require_relative '../task_execution_record'
+
+module RakeAudit
+  module Builders
+    # Assembles a {RakeAudit::TaskExecutionRecord} from the raw inputs gathered
+    # by {RakeAudit::ExecutionRecorder}: the task, its arguments, the timing
+    # window, and any exception that was raised.
+    #
+    # Environment fields (hostname, pid, ruby version, rails env) are captured
+    # here and are individually gated by the active {RakeAudit::Configuration}.
+    module TaskExecutionRecordBuilder
+      module_function
+
+      # Build a record describing one execution.
+      #
+      # @param task [#name] the executed Rake task (only +#name+ is required).
+      # @param args [Object, nil] arguments passed to the task.
+      # @param started_at [Time] when execution began.
+      # @param finished_at [Time] when execution finished (success or failure).
+      # @param exception [Exception, nil] the raised exception, if the task failed.
+      # @param config [RakeAudit::Configuration] configuration controlling capture.
+      # @return [RakeAudit::TaskExecutionRecord]
+      # rubocop:disable Metrics/ParameterLists, Metrics/CyclomaticComplexity
+      def build(task:, args:, started_at:, finished_at:, exception:, config:)
+        TaskExecutionRecord.new(
+          task_name: task_name_for(task),
+          arguments: normalize_arguments(args),
+          started_at: started_at,
+          finished_at: finished_at,
+          duration_ms: duration_ms_for(started_at, finished_at),
+          status: exception ? 'failure' : 'success',
+          error_class: exception&.class&.name,
+          error_message: exception&.message,
+          hostname: config.capture_hostname ? Socket.gethostname : nil,
+          pid: config.capture_pid ? Process.pid : nil,
+          ruby_version: config.capture_ruby_version ? RUBY_VERSION : nil,
+          rails_env: config.capture_rails_env ? rails_env : nil
+        )
+      end
+      # rubocop:enable Metrics/ParameterLists, Metrics/CyclomaticComplexity
+
+      # @api private
+      def task_name_for(task)
+        task.respond_to?(:name) ? task.name.to_s : task.to_s
+      end
+
+      # Coerce the task arguments into a plain Hash for stable serialization.
+      #
+      # Rake passes a +Rake::TaskArguments+ which responds to +#to_hash+; we also
+      # accept a raw Hash and treat anything else (including +nil+) as empty.
+      #
+      # @api private
+      # @return [Hash]
+      def normalize_arguments(args)
+        if args.respond_to?(:to_hash)
+          args.to_hash
+        else
+          {}
+        end
+      end
+
+      # @api private
+      # @return [Integer] elapsed wall-clock time in whole milliseconds.
+      def duration_ms_for(started_at, finished_at)
+        ((finished_at - started_at) * 1000).round
+      end
+
+      # @api private
+      # @return [String, nil] the current Rails environment, when available.
+      def rails_env
+        return nil unless defined?(Rails) && Rails.respond_to?(:env)
+
+        Rails.env.to_s
+      end
+    end
+  end
+end

data/lib/rake_audit/configuration.rb

@@ -0,0 +1,62 @@
+# frozen_string_literal: true
+
+require 'logger'
+
+module RakeAudit
+  # Holds all tunable settings for RakeAudit.
+  #
+  # An instance is created lazily by {RakeAudit.config} and mutated through
+  # {RakeAudit.configure}. All attributes carry sane defaults so that the gem
+  # is safe to load even when nothing has been configured.
+  class Configuration
+    # @return [Object, nil] storage adapter instance responding to +#save(record)+.
+    #   When +nil+, recording is a no-op.
+    attr_accessor :adapter
+
+    # @return [Logger] logger used to report adapter save failures.
+    attr_accessor :logger
+
+    # @return [Boolean] whether to capture the machine hostname.
+    attr_accessor :capture_hostname
+
+    # @return [Boolean] whether to capture the process id.
+    attr_accessor :capture_pid
+
+    # @return [Boolean] whether to capture the Ruby version.
+    attr_accessor :capture_ruby_version
+
+    # @return [Boolean] whether to capture the Rails environment.
+    attr_accessor :capture_rails_env
+
+    # @return [Boolean] whether the bundled Web UI is enabled.
+    attr_accessor :web_ui_enabled
+
+    # @return [Proc, nil] callable used to authenticate Web UI requests.
+    attr_accessor :authenticate_with
+
+    def initialize
+      @adapter = nil
+      @logger = default_logger
+      @capture_hostname = true
+      @capture_pid = true
+      @capture_ruby_version = true
+      @capture_rails_env = true
+      @web_ui_enabled = true
+      @authenticate_with = nil
+    end
+
+    private
+
+    # Prefer +Rails.logger+ when running inside a Rails app, otherwise fall back
+    # to a plain stdout logger so the gem works standalone.
+    #
+    # @return [Logger]
+    def default_logger
+      if defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+        Rails.logger
+      else
+        Logger.new($stdout)
+      end
+    end
+  end
+end

data/lib/rake_audit/execution_recorder.rb

@@ -0,0 +1,78 @@
+# frozen_string_literal: true
+
+require_relative 'builders/task_execution_record_builder'
+
+module RakeAudit
+  # Wraps a single Rake task execution to capture timing, success/failure, and
+  # any raised exception, then persists a {TaskExecutionRecord} via the
+  # configured adapter.
+  #
+  # Design invariants:
+  # - The original task exception always propagates unchanged (re-raised).
+  # - Persistence happens in an +ensure+ block so it runs on both success and
+  #   failure paths.
+  # - Adapter errors are logged and swallowed; they never affect the task result.
+  # - When no adapter is configured, saving is skipped entirely.
+  class ExecutionRecorder
+    # @param task [#name] the Rake task being executed.
+    # @param args [Object, nil] arguments passed to the task.
+    def initialize(task:, args: nil)
+      @task = task
+      @args = args
+    end
+
+    # Execute the given block, capturing timing and outcome.
+    #
+    # @yield runs the wrapped task body (typically +super+ from the patch).
+    # @return [Object] the block's return value on success.
+    # @raise [Exception] re-raises whatever the block raised, unchanged.
+    def record
+      started_at = now
+      exception = nil
+      begin
+        yield
+      rescue Exception => e # rubocop:disable Lint/RescueException
+        exception = e
+        raise
+      ensure
+        finished_at = now
+        save_record(started_at: started_at, finished_at: finished_at, exception: exception)
+      end
+    end
+
+    private
+
+    attr_reader :task, :args
+
+    # Build and persist the record. Never raises: adapter failures are logged.
+    def save_record(started_at:, finished_at:, exception:)
+      config = RakeAudit.config
+      adapter = config.adapter
+      return if adapter.nil?
+
+      record = Builders::TaskExecutionRecordBuilder.build(
+        task: task,
+        args: args,
+        started_at: started_at,
+        finished_at: finished_at,
+        exception: exception,
+        config: config
+      )
+      adapter.save(record)
+    rescue StandardError => e
+      log_save_failure(config, e)
+    end
+
+    def log_save_failure(config, error)
+      logger = config&.logger
+      return unless logger.respond_to?(:error)
+
+      logger.error("[RakeAudit] Save failed: #{error.class}: #{error.message}")
+    end
+
+    # @return [Time] monotonic-friendly current wall-clock time.
+    def now
+      Time.now
+    end
+  end
+end

data/lib/rake_audit/rails/engine.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+# Kaminari powers the execution list's pagination (+.page+ in the controller and
+# the +paginate+ helper in the view). Requiring it alongside the Engine — which
+# is itself only loaded when Rails is present — guarantees Kaminari's
+# ActiveRecord and ActionView integrations are active for the Web UI without
+# forcing the dependency on a plain-Ruby (no Rails) load of the gem.
+require 'kaminari'
+
+module RakeAudit
+  # Rails Engine for RakeAudit.
+  #
+  # Mounting an isolated Engine namespaces the gem's models, controllers, and
+  # routes under +RakeAudit+ so they never collide with the host application.
+  # The Engine also makes the gem's +app/+ directory part of the host app's
+  # load paths, which is how {RakeAudit::TaskExecution} becomes autoloadable.
+  class Engine < ::Rails::Engine
+    isolate_namespace RakeAudit
+  end
+end

data/lib/rake_audit/rails/railtie.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+module RakeAudit
+  # Hooks RakeAudit into the Rails boot process.
+  #
+  # The {RakeAudit::TaskPatch} is prepended into +Rake::Task+ only after the
+  # full Rails application has initialized, and only when a storage adapter has
+  # been configured. Deferring to +after_initialize+ guarantees that the
+  # initializer (e.g. +config/initializers/rake_audit.rb+) has already run and
+  # that every dependency the adapter needs is loaded; skipping the prepend when
+  # no adapter is present keeps recording a true no-op for unconfigured apps.
+  class Railtie < ::Rails::Railtie
+    config.after_initialize do
+      RakeAudit.install! if RakeAudit.config.adapter
+    end
+  end
+end

data/lib/rake_audit/record_not_found.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RakeAudit
+  class RecordNotFound < StandardError; end
+end

data/lib/rake_audit/task_execution_record.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+module RakeAudit
+  # Immutable data transfer object describing a single Rake task execution.
+  #
+  # This Struct is the serialization boundary used by every storage adapter:
+  # adapters must rely on {#to_h} and never reach into internal state directly.
+  TaskExecutionRecord = Struct.new(
+    :task_name,
+    :arguments,
+    :started_at,
+    :finished_at,
+    :duration_ms,
+    :status,
+    :error_class,
+    :error_message,
+    :hostname,
+    :pid,
+    :ruby_version,
+    :rails_env,
+    keyword_init: true
+  ) do
+    # The canonical, adapter-facing serialization of this record.
+    #
+    # Always returns a plain Hash containing all 12 fields, regardless of how
+    # the record was constructed. Adapters depend on this exact contract.
+    #
+    # @return [Hash{Symbol=>Object}]
+    def to_h
+      {
+        task_name: task_name,
+        arguments: arguments,
+        started_at: started_at,
+        finished_at: finished_at,
+        duration_ms: duration_ms,
+        status: status,
+        error_class: error_class,
+        error_message: error_message,
+        hostname: hostname,
+        pid: pid,
+        ruby_version: ruby_version,
+        rails_env: rails_env
+      }
+    end
+  end
+end

data/lib/rake_audit/task_patch.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+require_relative 'execution_recorder'
+
+module RakeAudit
+  # Module prepended into +Rake::Task+ so that every executed task is routed
+  # through an {ExecutionRecorder}. Prepending lets us wrap +#execute+ while
+  # still delegating to the original implementation via +super+.
+  module TaskPatch
+    # Intercept Rake task execution.
+    #
+    # @param args [Object, nil] arguments Rake passes to the task.
+    # @return [Object] the original +#execute+ return value.
+    # @raise [Exception] propagates whatever the underlying task raised.
+    def execute(args = nil)
+      ExecutionRecorder.new(task: self, args: args).record { super }
+    end
+  end
+end

data/lib/rake_audit/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module RakeAudit
+  VERSION = '0.1.0'
+end

data/lib/rake_audit.rb

@@ -0,0 +1,82 @@
+# frozen_string_literal: true
+
+require_relative 'rake_audit/version'
+require_relative 'rake_audit/record_not_found'
+require_relative 'rake_audit/configuration'
+require_relative 'rake_audit/task_execution_record'
+require_relative 'rake_audit/builders/task_execution_record_builder'
+require_relative 'rake_audit/execution_recorder'
+require_relative 'rake_audit/task_patch'
+
+# Top-level namespace and public entry point for the gem.
+#
+# Typical usage:
+#
+#   RakeAudit.configure do |c|
+#     c.adapter = MyAdapter.new
+#   end
+#
+# Loading this file also installs the {RakeAudit::TaskPatch} into +Rake::Task+
+# when Rake is available, so task execution is recorded automatically.
+module RakeAudit
+  # Error namespace base class for the gem.
+  class Error < StandardError; end
+
+  class << self
+    # The current configuration, created on first access.
+    #
+    # @return [RakeAudit::Configuration]
+    def config
+      @config ||= Configuration.new
+    end
+
+    alias configuration config
+
+    # Yield the configuration for mutation.
+    #
+    #   RakeAudit.configure { |c| c.adapter = MyAdapter.new }
+    #
+    # @yieldparam config [RakeAudit::Configuration]
+    # @return [RakeAudit::Configuration]
+    def configure
+      yield config if block_given?
+      config
+    end
+
+    # Reset configuration to defaults. Primarily useful in tests.
+    #
+    # @return [RakeAudit::Configuration]
+    def reset_config!
+      @config = Configuration.new
+    end
+
+    # Install the execution hook into +Rake::Task+.
+    #
+    # Idempotent: prepending the same module twice is a no-op in Ruby, so this
+    # is safe to call multiple times.
+    #
+    # @return [Boolean] true if Rake was present and the patch is installed.
+    # rubocop:disable Naming/PredicateMethod
+    def install!
+      return false unless defined?(Rake::Task)
+
+      Rake::Task.prepend(TaskPatch)
+      true
+    end
+    # rubocop:enable Naming/PredicateMethod
+  end
+end
+
+# Load the Rails integration only when Rails is present. The Engine exposes the
+# gem's +app/+ models to the host application and the Railtie installs the task
+# patch after initialization; both require Rails and are skipped otherwise so
+# the gem remains usable in a plain Ruby or standalone Rake setup.
+if defined?(Rails::Engine)
+  require_relative 'rake_audit/rails/engine'
+  require_relative 'rake_audit/rails/railtie'
+end
+
+# Auto-install the patch when Rake is already loaded. When Rake loads later
+# (e.g. a Railtie or the application's Rakefile), callers can invoke
+# RakeAudit.install! explicitly.
+RakeAudit.install!