wipe_out 1.0.0

data/docs/releasing.md

@@ -0,0 +1,14 @@
+# Releasing
+
+1. Update `VERSION` in `lib/wipe_out/version.rb`. Please follow [semver](https://semver.org/)
+1. Update [CHANGELOG.md](../CHANGELOG.md)
+   * Make sure any breaking change has notes and is clearly visible
+1. Commit your changes to `master`
+1. Create a new tag called `vX.Y.Z` where X, Y and Z are major, minor and patch versions.
+
+   ```bash
+   git tag -s vVERSION
+   ```
+
+1. Push changes: `git push && git push --tags`
+1. Create new [Github Release](https://github.com/GlobalAppTesting/wipe_out/releases/new?tag=vVERSION)

data/docs/yard_plugin.rb

@@ -0,0 +1,12 @@
+require "yard"
+# https://github.com/troessner/reek/blob/87b0e75091552c59fcf20105016ba6ce97a57b06/docs/yard_plugin.rb
+module LocalLinkHelper
+  # Rewrites links to (assumed local) markdown files so they're processed as
+  # {file: } directives.
+  def resolve_links(text)
+    text = text.gsub(%r{<a href="([^"]*.md)">([^<]*)</a>}, '{file:\1 \2}')
+    super(text)
+  end
+end
+
+YARD::Templates::Template.extra_includes << LocalLinkHelper

data/lib/wipe_out.rb

@@ -0,0 +1,65 @@
+require "attr_extras"
+require "forwardable"
+require "zeitwerk"
+
+loader = Zeitwerk::Loader.for_gem
+loader.setup
+
+# When working with gem please see {file:getting_started.md}
+#
+# If you'd like to contribute, check out {file:development.md}
+#
+module WipeOut
+  IGNORE_ALL = :ignore_all
+
+  class << self
+    extend Forwardable
+    # Builds a plan for wipe out. When ActiveRecord class is passed,
+    #
+    # @example
+    #   UserPlan = WipeOut.build_plan do
+    #     wipe_out :name
+    #   end
+    #
+    #
+    # For DSL documentation {Plans::Dsl}
+    #
+    # @return [Plans::BuiltPlan]
+    #
+    def build_plan(config: nil, &block)
+      config ||= WipeOut.config.dup
+      plan = Plans::Plan.new(config)
+      Plans::Dsl.build(plan, &block)
+    end
+
+    # Configures the gem, you should call it in the initializer
+    #
+    # @example
+    #   WipeOut.configure do |config|
+    #     config.ignored_attributes = %i[id inserted_at]
+    #   end
+    #
+    # For additional details, {Config}.
+    # You will be also able to modify config for specific plan.
+    # Here you only set defaults.
+    #
+    # @return [Config]
+    def configure
+      raise "Pass block to configure the gem" unless block_given?
+
+      yield config
+
+      config
+    end
+
+    # Returns current configuration
+    #
+    # @return [Config]
+    def config
+      @config ||= Config.new
+    end
+    def_delegators :@config, :logger
+  end
+end
+
+loader.eager_load

data/lib/wipe_out/attribute_strategies/const_value.rb

@@ -0,0 +1,13 @@
+module WipeOut
+  module AttributeStrategies
+    class ConstValue
+      def initialize(value)
+        @value = value
+      end
+
+      def call(*)
+        @value
+      end
+    end
+  end
+end

data/lib/wipe_out/attribute_strategies/nullify.rb

@@ -0,0 +1,5 @@
+module WipeOut
+  module AttributeStrategies
+    Nullify = ConstValue.new(nil)
+  end
+end

data/lib/wipe_out/attribute_strategies/randomize.rb

@@ -0,0 +1,13 @@
+module WipeOut
+  module AttributeStrategies
+    class Randomize
+      def initialize(format: "destroyed_%s")
+        @format = format
+      end
+
+      def call(*)
+        @format % SecureRandom.hex(10)
+      end
+    end
+  end
+end

data/lib/wipe_out/callback.rb

@@ -0,0 +1,25 @@
+module WipeOut
+  class Callback
+    attr_reader :name
+
+    def initialize(name, block)
+      @name = name.to_sym
+      @block = block
+    end
+
+    def run(execution)
+      raise("Wrong arity for callback name=#{name}") if block.arity != 1
+
+      block.call(execution)
+    end
+
+    def ==(other)
+      name == other.name &&
+        block == other.block
+    end
+
+    private
+
+    attr_reader :block
+  end
+end

data/lib/wipe_out/callbacks_observer.rb

@@ -0,0 +1,23 @@
+module WipeOut
+  # @api private
+  class CallbacksObserver
+    def initialize(callbacks, execution)
+      @callbacks = callbacks
+      @execution = execution
+    end
+
+    def update(name)
+      callbacks_by_name(name).each do |callback|
+        callback.run(execution)
+      end
+    end
+
+    private
+
+    attr_reader :execution, :callbacks
+
+    def callbacks_by_name(name)
+      callbacks.select { |callback| callback.name == name }
+    end
+  end
+end

data/lib/wipe_out/config.rb

@@ -0,0 +1,30 @@
+module WipeOut
+  # Holds configuration for the gem.
+  #
+  # Configuration options:
+  #
+  #   - ignored_attributes - default: `%i[id updated_at created_at archived_at]`
+  #     these attributes will be ignored in every plan by default.
+  #   - logger - default: Rails.logger
+  #   - default_on_execute - default: calls `save!` on record
+  #
+  class Config
+    # @!visibility private
+    attr_accessor :ignored_attributes, :logger, :default_on_execute
+
+    def initialize
+      @default_on_execute = ->(execution) { execution.record.save! }
+      @ignored_attributes = %i[id updated_at created_at archived_at]
+      @logger = Rails.logger
+    end
+
+    # Duplicates config
+    def dup
+      config = self.class.new
+      config.ignored_attributes = ignored_attributes
+      config.logger = logger
+      config.default_on_execute = default_on_execute
+      config
+    end
+  end
+end

data/lib/wipe_out/execute.rb

@@ -0,0 +1,31 @@
+module WipeOut
+  # Executes plan for a given record.
+  # Plan execution flow:
+  #   - emit event: `#before_plan`
+  #
+  # For each record (recursively, depth first)
+  #   - emit event: `#before_execution`
+  #   - emit event: `#after_execution`
+  #
+  # After plan had been executed (won't run if exception had been raised)
+  #   - emit event: `#after_plan`
+  #
+  # To see how plan is defined, see {Plans::Dsl}
+  # To configure, see {Config}
+  #
+  class Execute
+    method_object :plan, :ar_class, :record
+
+    def call
+      ar_class.transaction do
+        execution = Execution::Context.new(plan, record)
+
+        execution.notify(:before_plan)
+
+        Execution::ExecutePlan.call(execution)
+
+        execution.notify(:after_plan)
+      end
+    end
+  end
+end

data/lib/wipe_out/execution/context.rb

@@ -0,0 +1,34 @@
+require "observer"
+
+module WipeOut
+  module Execution
+    class Context
+      include Observable
+      attr_reader :record, :plan, :config
+
+      def initialize(plan, record, config = plan.config)
+        @plan = plan
+        @record = record
+        @config = config
+
+        add_observer(CallbacksObserver.new(plan.callbacks, self))
+      end
+
+      def run
+        on_execute = plan.on_execute || config.default_on_execute
+
+        on_execute.call(self)
+      end
+
+      def notify(name)
+        changed
+        notify_observers(name)
+      end
+
+      def subexecution(sub_plan, record)
+        plan.callbacks.each { |callback| sub_plan.add_callback(callback) }
+        self.class.new(sub_plan, record, config)
+      end
+    end
+  end
+end

data/lib/wipe_out/execution/execute_plan.rb

@@ -0,0 +1,53 @@
+require "forwardable"
+
+module WipeOut
+  module Execution
+    class ExecutePlan
+      extend Forwardable
+      method_object :execution
+
+      def_delegators :@execution, :plan, :record
+
+      def call
+        execution.notify(:before_execution)
+
+        process_relations
+        plan.attributes.each(&method(:execute_on_attribute))
+
+        execution.run
+
+        execution.notify(:after_execution)
+      end
+
+      def process_relations
+        plan.relations.each do |name, plan|
+          relation = record.send(name)
+
+          next unless relation.present?
+
+          if collection?(record, name)
+            relation.find_each { |record| execute_on_record(plan, record) }
+          else
+            execute_on_record(plan, relation)
+          end
+        end
+      end
+
+      def execute_on_attribute(attribute)
+        name, strategy = attribute
+        value = strategy.call(record, name)
+        record.send("#{name}=", value)
+      end
+
+      def execute_on_record(plan, record)
+        execution_plan = plan.establish_execution_plan(record)
+
+        ExecutePlan.call(execution.subexecution(execution_plan, record))
+      end
+
+      def collection?(record, relation_name)
+        record.class.reflect_on_association(relation_name).collection?
+      end
+    end
+  end
+end

data/lib/wipe_out/plans/built_plan.rb

@@ -0,0 +1,35 @@
+module WipeOut
+  module Plans
+    # Provides final API after the plan had been build
+    #
+    # Under the hood it contains plans but hides our under the hood
+    # implemention where we have helper methods for adding relations, attributes, etc.
+    class BuiltPlan
+      extend Forwardable
+
+      def initialize(plan)
+        @plan = plan
+      end
+
+      def_delegators :plan, :config
+      attr_reader :plan
+
+      # Validates and returns any errors if validation fails.
+      #
+      # It's not done automatically when plan is defined because plans
+      # can be combined and not be valid standalone.
+      #
+      # @return [Array<String>] empty if everything is OK with the plan.
+      #   Returns non-empty list if issues are detected.
+      #   You should call it in tests to ensure that plans are OK.
+      def validate(ar_class)
+        WipeOut::Validate.call(plan, ar_class, @plan.config)
+      end
+
+      # Executes plan on a record
+      def execute(record)
+        WipeOut::Execute.call(plan, record.class, record)
+      end
+    end
+  end
+end

data/lib/wipe_out/plans/dsl.rb

@@ -0,0 +1,117 @@
+require "forwardable"
+
+module WipeOut
+  module Plans
+    # Provides DSL methods available during {Plan} building.
+    class Dsl
+      extend Forwardable
+      include WipeOut::Plugin::ClassMethods
+      # {#WipeOut.build_plan WipeOut.build_plan} should be used instead
+      #
+      # @!visibility private
+      def self.build(plan, &block)
+        dsl = Dsl.new(plan)
+        dsl.instance_exec(&block)
+
+        BuiltPlan.new(dsl.plan)
+      end
+
+      # @!visibility private
+      attr_reader :plan
+
+      # @!method on_execute
+      #   Overwrites default `#save!` which is called on record after wipe out.
+      #   You can use this to switch to `#destroy!` or `#delete!` if needed.
+      #   You can also configure this in {Config}
+      #
+      #   @yield [WipeOut::Execution::Context] execution
+      #   @return [nil]
+      #
+      # @!method include_plan!(other_plan)
+      #
+      #   Combines plan with another one. You can use it to create plans
+      #   out of other plans via composition.
+      #
+      #   @param [WipeOut::Plans::Plan] other_plan
+      #   @return {nil}
+      def_delegators :@plan, :on_execute
+
+      # @!visibility private
+      def initialize(plan)
+        @plan = plan
+      end
+
+      # @!visibility private
+      def plugin(plugin)
+        plugin.callbacks.each { |callback| add_callback(callback) }
+      end
+
+      # Defines a strategy for removing data inside attribute(s)
+      #
+      # @param names [Array<Symbol>] any number of attributes to wipe out
+      # @param strategy [#call] defined a strategy which should be used for wiping out the attribute(s).
+      #   You can also define a strategy inline by passing a block.
+      #   By default it uses {AttributeStrategies::Nullify}.
+      # @return [nil]
+      def wipe_out(*names, strategy: AttributeStrategies::Nullify, &block)
+        strategy = block if block
+        names.each do |name|
+          plan.add_attribute(name, strategy: strategy)
+        end
+      end
+
+      # Configures plan for wiping out data in relation. You must pass a block
+      # and use the same DSL to configure it.
+      #
+      # @return [nil]
+      def relation(name, plan = nil, plans: nil, &block)
+        if plans
+          @plan.add_relation_union(name, plans.map(&:plan), &block)
+        else
+          plan ||= Plan.new(@plan.config)
+          plan = plan.plan if plan.is_a?(BuiltPlan)
+          dsl = Dsl.new(plan)
+          dsl.instance_exec(&block) if block.present?
+
+          @plan.add_relation(name, dsl.plan)
+        end
+      end
+
+      # Sets given attribute(s) as ignored. Attributes must be ignored explicily
+      # otherwise errors will be raised during validation
+      #
+      # @param names [Array<Symbol>] any number of attributes to ignore
+      # @return [nil]
+      def ignore(*names)
+        names.each do |name|
+          plan.ignore(name)
+        end
+      end
+
+      # Ignores all attributes and relations during validation.
+      # It should be used when you're using custom `#on_execute` method that
+      # for example destroys records and you don't care what attributes are there exactly
+      def ignore_all
+        plan.ignore(WipeOut::IGNORE_ALL)
+      end
+
+      def include_plan(built_plan)
+        plan.include_plan(built_plan.plan)
+      end
+
+      # See {Config} to check what options are available.
+      # @todo add test for nested configurations inside plans
+      # @return [Config]
+      def configure
+        yield plan.config
+
+        plan.config
+      end
+
+      # @!visibility private
+      def add_callback(callback)
+        plan.add_callback(callback)
+      end
+    end
+  end
+end