trakable 0.2.0

data/lib/trakable/trak.rb

@@ -0,0 +1,98 @@
+# frozen_string_literal: true
+
+module Trakable
+  # Trak model for storing audit records.
+  # Each trak represents a single state change event on a tracked item.
+  #
+  # Inherits from ActiveRecord::Base when available (Rails apps),
+  # otherwise works as a plain Ruby object (testing, non-AR contexts).
+  #
+  class Trak < (defined?(ActiveRecord::Base) ? ActiveRecord::Base : Object)
+    include Revertable
+
+    EVENTS = %w[create update destroy].freeze
+
+    if defined?(ActiveRecord::Base) && self < ActiveRecord::Base
+      require 'json'
+
+      self.table_name = 'traks'
+
+      serialize :object, coder: JSON
+      serialize :changeset, coder: JSON
+      serialize :metadata, coder: JSON
+
+      belongs_to :item, polymorphic: true, optional: true
+      belongs_to :whodunnit, polymorphic: true, optional: true
+
+      scope :for_item_type, ->(type) { where(item_type: type.to_s) }
+      scope :for_event, ->(event) { where(event: event.to_s) }
+      scope :for_whodunnit, ->(user) { where(whodunnit_type: user.class.name, whodunnit_id: user.id) }
+      scope :created_before, ->(time) { where(arel_table[:created_at].lt(time)) }
+      scope :created_after, ->(time) { where(arel_table[:created_at].gt(time)) }
+      scope :recent, -> { order(created_at: :desc) }
+    else
+      ATTRS = %i[id item_type item_id event object changeset
+                 whodunnit_type whodunnit_id metadata created_at].freeze
+
+      # Pre-computed ivar symbols to avoid string interpolation in initialize
+      ATTR_IVARS = ATTRS.to_h { |a| [a, :"@#{a}"] }.freeze
+
+      attr_accessor(*ATTRS)
+
+      def initialize(attrs = {})
+        attrs.each do |key, value|
+          ivar = ATTR_IVARS[key]
+          instance_variable_set(ivar, value) if ivar
+        end
+      end
+
+      def self.table_name
+        'traks'
+      end
+
+      def item
+        return nil unless item_type && item_id
+
+        @item ||= item_type.constantize.find_by(id: item_id)
+      rescue NameError
+        nil
+      end
+
+      def whodunnit
+        return nil unless whodunnit_type && whodunnit_id
+
+        @whodunnit ||= whodunnit_type.constantize.find_by(id: whodunnit_id)
+      rescue NameError
+        nil
+      end
+    end
+
+    class << self
+      def build(item:, event:, changeset:, object: nil, whodunnit: nil, metadata: nil)
+        new(
+          item_type: item.class.name,
+          item_id: item.id,
+          event: event,
+          object: object,
+          changeset: changeset,
+          whodunnit_type: whodunnit&.class&.name,
+          whodunnit_id: whodunnit&.id,
+          metadata: metadata,
+          created_at: Time.now
+        )
+      end
+    end
+
+    def create?
+      event == 'create'
+    end
+
+    def update?
+      event == 'update'
+    end
+
+    def destroy?
+      event == 'destroy'
+    end
+  end
+end

data/lib/trakable/version.rb

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

data/lib/trakable.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+require_relative 'trakable/version'
+
+# Trakable provides audit logging and version tracking for ActiveRecord models.
+# It offers polymorphic whodunnit tracking, changesets, and built-in retention.
+module Trakable
+  @configuration = nil
+
+  class << self
+    # Returns the global configuration.
+    # Eagerly initialized after require to eliminate thread-safety race.
+    def configuration
+      @configuration ||= Configuration.new
+    end
+
+    def configure
+      yield(configuration)
+    end
+
+    def enabled?
+      configuration.enabled
+    end
+
+    def with_user(user, &)
+      Context.with_user(user, &)
+    end
+
+    def with_tracking(&)
+      Context.with_tracking(&)
+    end
+
+    def without_tracking(&)
+      Context.without_tracking(&)
+    end
+  end
+end
+
+require_relative 'trakable/cleanup'
+require_relative 'trakable/config'
+require_relative 'trakable/context'
+Trakable.autoload :Controller, 'trakable/controller'
+require_relative 'trakable/model'
+require_relative 'trakable/revertable'
+require_relative 'trakable/trak'
+require_relative 'trakable/tracker'
+
+require_relative 'trakable/railtie' if defined?(Rails::Railtie)
+
+# Eager-initialize configuration to eliminate thread-safety race on first access
+Trakable.configuration

data/trakable.gemspec

@@ -0,0 +1,41 @@
+# frozen_string_literal: true
+
+require_relative 'lib/trakable/version'
+
+Gem::Specification.new do |spec|
+  spec.name = 'trakable'
+  spec.version = Trakable::VERSION
+  spec.authors = ['Hadrien Blanc']
+  spec.email = ['trakable@hadrienblanc.com']
+
+  spec.summary = 'Audit and versioning for ActiveRecord models'
+  spec.description = 'Trakable provides audit logging and version tracking for ActiveRecord models with polymorphic whodunnit, changesets, and built-in retention'
+  spec.homepage = 'https://github.com/hadrienblanc/trakable'
+  spec.license = 'MIT'
+  spec.required_ruby_version = '>= 3.1.0'
+
+  spec.metadata['homepage_uri'] = spec.homepage
+  spec.metadata['source_code_uri'] = spec.homepage
+  spec.metadata['changelog_uri'] = "#{spec.homepage}/blob/main/CHANGELOG.md"
+
+  # Specify which files should be included in the gem
+  spec.files = Dir.chdir(__dir__) do
+    `git ls-files -z`.split("\x0").reject do |f|
+      (File.expand_path(f) == __FILE__) ||
+        f.start_with?(*%w[bin/ test/ spec/ features/ .git .github appveyor Gemfile])
+    end
+  end
+  spec.bindir = 'exe'
+  spec.executables = spec.files.grep(%r{\Aexe/}) { |f| File.basename(f) }
+  spec.require_paths = ['lib']
+
+  spec.add_dependency 'activerecord', '>= 7.1', '< 8.2'
+  spec.add_dependency 'activesupport', '>= 7.1', '< 8.2'
+
+  spec.add_development_dependency 'minitest', '~> 5.25'
+  spec.add_development_dependency 'railties', '>= 7.1', '< 8.2'
+  spec.add_development_dependency 'rake', '~> 13.0'
+  spec.add_development_dependency 'rubocop', '~> 1.69'
+  spec.add_development_dependency 'rubocop-minitest', '~> 0.37'
+  spec.add_development_dependency 'sqlite3', '~> 2.5'
+end

metadata

@@ -0,0 +1,242 @@
+--- !ruby/object:Gem::Specification
+name: trakable
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Hadrien Blanc
+bindir: exe
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: activerecord
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.25'
+- !ruby/object:Gem::Dependency
+  name: railties
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '7.1'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '8.2'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '13.0'
+- !ruby/object:Gem::Dependency
+  name: rubocop
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.69'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.69'
+- !ruby/object:Gem::Dependency
+  name: rubocop-minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.37'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '0.37'
+- !ruby/object:Gem::Dependency
+  name: sqlite3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '2.5'
+description: Trakable provides audit logging and version tracking for ActiveRecord
+  models with polymorphic whodunnit, changesets, and built-in retention
+email:
+- trakable@hadrienblanc.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rubocop.yml"
+- CHANGELOG.md
+- LICENSE
+- README.md
+- Rakefile
+- benchmark/full_benchmark.rb
+- benchmark/integration_memory.rb
+- benchmark/memory_benchmark.rb
+- benchmark/perf_benchmark.rb
+- integration/README.md
+- integration/run_all.rb
+- integration/scenarios/01-basic-tracking/scenario.rb
+- integration/scenarios/02-revert-restoration/scenario.rb
+- integration/scenarios/03-whodunnit-tracking/scenario.rb
+- integration/scenarios/04-cleanup-retention/scenario.rb
+- integration/scenarios/05-without-tracking/scenario.rb
+- integration/scenarios/06-callback-lifecycle/scenario.rb
+- integration/scenarios/07-global-config/scenario.rb
+- integration/scenarios/08-controller-integration/scenario.rb
+- integration/scenarios/09-cleanup-max-traks/scenario.rb
+- integration/scenarios/10-model-configuration/scenario.rb
+- integration/scenarios/11-conditional-tracking/scenario.rb
+- integration/scenarios/12-metadata/scenario.rb
+- integration/scenarios/13-traks-association/scenario.rb
+- integration/scenarios/14-time-travel/scenario.rb
+- integration/scenarios/15-diffing-changeset/scenario.rb
+- integration/scenarios/16-serialization/scenario.rb
+- integration/scenarios/17-associations-tracking/scenario.rb
+- integration/scenarios/18-bulk-operations/scenario.rb
+- integration/scenarios/19-transactions/scenario.rb
+- integration/scenarios/20-performance/scenario.rb
+- integration/scenarios/21-storage-backends/scenario.rb
+- integration/scenarios/22-multi-tenancy/scenario.rb
+- integration/scenarios/23-sti/scenario.rb
+- integration/scenarios/24-edge-cases-part1/scenario.rb
+- integration/scenarios/25-edge-cases-part2/scenario.rb
+- integration/scenarios/26-edge-cases-part3/scenario.rb
+- integration/scenarios/27-api-query-interface/scenario.rb
+- integration/scenarios/28-security-compliance/scenario.rb
+- integration/scenarios/29-soft-delete/scenario.rb
+- integration/scenarios/30-custom-events/scenario.rb
+- integration/scenarios/31-gem-packaging/scenario.rb
+- integration/scenarios/32-bypass-fail-closed/scenario.rb
+- integration/scenarios/33-coexistence-standalone/scenario.rb
+- integration/scenarios/34-real-tracking/scenario.rb
+- integration/scenarios/35-revert-undo/scenario.rb
+- integration/scenarios/36-whodunnit-deep/scenario.rb
+- integration/scenarios/37-real-world-use-cases/scenario.rb
+- integration/scenarios/38-concurrency/scenario.rb
+- integration/scenarios/39-query-scopes/scenario.rb
+- integration/scenarios/40-whodunnit-config/scenario.rb
+- integration/scenarios/41-batch-cleanup/scenario.rb
+- integration/scenarios/scenario_runner.rb
+- lib/generators/trakable/install_generator.rb
+- lib/generators/trakable/templates/create_traks_migration.rb
+- lib/generators/trakable/templates/trakable_initializer.rb
+- lib/trakable.rb
+- lib/trakable/cleanup.rb
+- lib/trakable/config.rb
+- lib/trakable/context.rb
+- lib/trakable/controller.rb
+- lib/trakable/model.rb
+- lib/trakable/railtie.rb
+- lib/trakable/revertable.rb
+- lib/trakable/tracker.rb
+- lib/trakable/trak.rb
+- lib/trakable/version.rb
+- trakable.gemspec
+homepage: https://github.com/hadrienblanc/trakable
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/hadrienblanc/trakable
+  source_code_uri: https://github.com/hadrienblanc/trakable
+  changelog_uri: https://github.com/hadrienblanc/trakable/blob/main/CHANGELOG.md
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.9
+specification_version: 4
+summary: Audit and versioning for ActiveRecord models
+test_files: []