data_shifter 0.2.0 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 8143cec17a5f8cb7374ad327338e694cea0a9422bf0392e005a3eaeeee9ab83d
-  data.tar.gz: b9a246478df8ef89377482951e74ad36b63655510f4bf3bbc6a1b4480edec85e
+  metadata.gz: 7c2c6cb1c13bba3100efe294ceeafd838f4c329650b323457b0a75296bbff28f
+  data.tar.gz: b2dfe9b104bcc97fe7f8d1524d9739cb6b5918885a64f0ccf58725a8477d4298
 SHA512:
-  metadata.gz: e8f150f146151d8a82ccc79fd2e31f2ed813ee1b631d0eb9fc5490fa201ed31890a088f24bb7bb086d4158407f5bfb3f969c639dad75d85809c72d44e609172e
-  data.tar.gz: b776d810b0819d216436e169414c9c09c0a0c1f7cc3123f58912fa638675f55c998c3c7be71bae40868c5fddbb031bd42d3b2b8a915491d9e6d792852712405f
+  metadata.gz: c501bef9515dae1a53a20dd4b40e4fb454c31b17a781b53df02b861f6ae0415f012a801f2b767f5975cd8cb5aa69555467de5a89dff4448b766ab410e23e7a5a
+  data.tar.gz: cd30ac7dcef93f800101c26a5472063859e8671270c58169083c7116fdd3cac2f6559efe6f9da084a2b7b939aa2ef0e909a96b816964043f8739d544a80fef34

data/CHANGELOG.md

@@ -4,6 +4,20 @@
 
 * N/A
 
+## [0.3.0]
+
+### Added
+
+- **Task-based shifts**: New `task` DSL for targeted, one-off changes without the `collection`/`process_record` pattern. Define one or more `task "label" do ... end` blocks that run in sequence with shared transaction and dry-run semantics. Labels appear in output and error messages.
+- **Generator `--task` option**: `rails g data_shift fix_order_1234 --task` generates a shift with a `task` block instead of `collection`/`process_record`.
+- **Colorized CLI output**: Headers, summaries, and status output now use ANSI colors for better readability. Colors are automatically disabled when output is not a TTY or when `NO_COLOR` environment variable is set.
+- **Cleaner summaries**: `Failed` and `Skipped` lines are now omitted from summaries when their values are zero.
+
+### Changed
+
+- **Improved error messages**: `NotImplementedError` messages for `collection` and `process_record` now suggest using `task` blocks as an alternative.
+- **Task labels logged on execution**: When running task-based shifts, each labeled task logs its name (`>> label`) when it starts.
+
 ## [0.2.0]
 
 ### Added

data/README.md

@@ -35,7 +35,9 @@ COMMIT=1 rake data:shift:backfill_foo
 
 ## Defining a shift
 
-Typical shifts implement:
+### Collection-based shifts (typical)
+
+For systemic migrations across many records, implement:
 
 - **`collection`**: an `ActiveRecord::Relation` (uses `find_each`) or an `Array`/Enumerable
 - **`process_record(record)`**: applies the change for one record
@@ -56,9 +58,48 @@ module DataShifts
 end
 ```
 
+### Task-based shifts (targeted, one-off changes)
+
+For targeted changes to specific records (e.g. fixing a bug for particular IDs), use `task` blocks instead:
+
+```ruby
+module DataShifts
+  class FixOrderDiscrepancies < DataShifter::Shift
+    description "Fix order #1234 shipping and billing issues"
+
+    task "Correct shipping address" do
+      order.update!(shipping_address: "123 Main St")
+    end
+
+    task "Apply missing discount" do
+      order.update!(discount_cents: 500)
+    end
+
+    private
+
+    def order
+      @order ||= Order.find(1234)
+    end
+  end
+end
+```
+
+Task blocks run in the context of the shift instance, so they have access to private helper methods, `dry_run?`, `log`, `skip!`, `find_exactly!`, and any other instance methods you define. Use private methods to DRY up shared lookups across tasks.
+
+Task blocks:
+
+- Run in sequence within the same lifecycle (transaction, dry run protection, summary)
+- Default to single transaction (all tasks commit or roll back together); use `transaction :per_record` for per-task transactions
+
+Generate a task-based shift with:
+
+```bash
+bin/rails generate data_shift fix_order_1234 --task
+```
+
 ## Dry run vs commit
 
-Shifts run in **dry run** mode by default. In the automatic transaction modes (`transaction :single` / `true`, and `transaction :per_record`), DB changes are rolled back automatically.
+Shifts run in **dry run** mode by default. DB changes are always rolled back in dry run mode, regardless of transaction setting.
 
 - **Dry run (default)**: `rake data:shift:backfill_foo`
 - **Commit**: `COMMIT=1 rake data:shift:backfill_foo`
@@ -277,6 +318,7 @@ end
 | `bin/rails generate data_shift backfill_foo` | `lib/data_shifts/<timestamp>_backfill_foo.rb` with a `DataShifts::BackfillFoo` class |
 | `bin/rails generate data_shift backfill_users --model User` | Same, with `User.all` in `collection` and `process_record(user)` |
 | `bin/rails generate data_shift backfill_users --spec` | Also generates `spec/lib/data_shifts/backfill_users_spec.rb` when RSpec is enabled |
+| `bin/rails generate data_shift fix_order_1234 --task` | Generates a shift with a `task` block instead of `collection`/`process_record` |
 
 The generator refuses to create a second shift if it would produce a duplicate rake task name.
 

data/lib/data_shifter/internal/colors.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+module DataShifter
+  module Internal
+    # ANSI color utilities for CLI output.
+    # Automatically detects TTY and respects NO_COLOR environment variable.
+    module Colors
+      CODES = {
+        reset: "\e[0m",
+        bold: "\e[1m",
+        dim: "\e[2m",
+        green: "\e[32m",
+        yellow: "\e[33m",
+        red: "\e[31m",
+        cyan: "\e[36m",
+      }.freeze
+
+      module_function
+
+      def enabled?(io = $stdout)
+        return false if ENV["NO_COLOR"]
+        return false unless io.respond_to?(:tty?)
+
+        io.tty?
+      end
+
+      def wrap(text, *styles, io: $stdout)
+        return text unless enabled?(io)
+
+        codes = styles.map { |s| CODES[s] }.compact.join
+        "#{codes}#{text}#{CODES[:reset]}"
+      end
+
+      def bold(text, io: $stdout)
+        wrap(text, :bold, io:)
+      end
+
+      def dim(text, io: $stdout)
+        wrap(text, :dim, io:)
+      end
+
+      def green(text, io: $stdout)
+        wrap(text, :green, io:)
+      end
+
+      def yellow(text, io: $stdout)
+        wrap(text, :yellow, io:)
+      end
+
+      def red(text, io: $stdout)
+        wrap(text, :red, io:)
+      end
+
+      def cyan(text, io: $stdout)
+        wrap(text, :cyan, io:)
+      end
+
+      def success(text, io: $stdout)
+        wrap(text, :bold, :green, io:)
+      end
+
+      def warning(text, io: $stdout)
+        wrap(text, :bold, :yellow, io:)
+      end
+
+      def error(text, io: $stdout)
+        wrap(text, :bold, :red, io:)
+      end
+    end
+  end
+end

data/lib/data_shifter/internal/output.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require_relative "colors"
+
 module DataShifter
   module Internal
     # Output formatting utilities for data shift runs.
@@ -12,131 +14,164 @@ module DataShifter
       }.freeze
 
       SKIP_REASONS_DISPLAY_LIMIT = 10
+      DIVIDER = "=" * 60
+      SEPARATOR = "-" * 60
 
       module_function
 
+      # --- Public header methods ---
+
       def print_header(io:, shift_class:, total:, label:, dry_run:, transaction_mode:, status_interval:)
-        io.puts ""
-        io.puts "=" * 60
-        io.puts shift_class.name || "DataShifter::Shift (anonymous)"
-        io.puts "\"#{shift_class.description}\"" if shift_class.description.present?
-        io.puts "-" * 60
-        io.puts "Mode:        #{dry_run ? "DRY RUN (no changes will be persisted)" : "LIVE"}"
+        print_header_top(io:, shift_class:, dry_run:)
         io.puts "Records:     #{total} #{label}"
         io.puts "Transaction: #{TRANSACTION_MODE_LABELS[transaction_mode]}"
+        print_header_bottom(io:, status_interval:)
+      end
 
-        status_line = build_status_line(status_interval)
-        io.puts "Status:      #{status_line} for live progress (no abort)" if status_line
-
-        io.puts "=" * 60
-        io.puts ""
+      def print_task_header(io:, shift_class:, block_count:, dry_run:, transaction_mode:, status_interval:)
+        print_header_top(io:, shift_class:, dry_run:)
+        io.puts "Tasks:       #{block_count}" if block_count >= 2
+        io.puts "Transaction: #{task_transaction_label(transaction_mode)}"
+        print_header_bottom(io:, status_interval:)
       end
 
+      # --- Public summary/progress methods ---
+
       def print_summary(io:, stats:, errors:, start_time:, dry_run:, transaction_mode:, interrupted:, task_name:, last_successful_id:, skip_reasons: {})
         return unless start_time
 
-        elapsed = (Time.current - start_time).round(1)
+        has_failures = stats[:failed].positive? || interrupted
+
         io.puts ""
-        io.puts "=" * 60
-        io.puts summary_title(dry_run:, interrupted:)
-        io.puts "-" * 60
-        io.puts "Duration:    #{elapsed}s"
-        io.puts "Processed:   #{stats[:processed]}"
-        io.puts "Succeeded:   #{stats[:succeeded]}"
-        io.puts "Failed:      #{stats[:failed]}"
-        io.puts "Skipped:     #{stats[:skipped]}"
-        print_skip_reasons(io:, skip_reasons:) if skip_reasons.any?
+        io.puts summary_divider(has_failures:, io:)
+        io.puts summary_title(dry_run:, interrupted:, has_failures:, io:)
+        io.puts Colors.dim(SEPARATOR, io:)
+        print_stats(io:, stats:, start_time:, skip_reasons:)
 
         print_errors(io:, errors:) if errors.any?
         print_interrupt_warning(io:, transaction_mode:, dry_run:) if interrupted
         print_dry_run_instructions(io:, task_name:) if dry_run && !interrupted
         print_continue_from_hint(io:, task_name:, last_successful_id:, dry_run:, transaction_mode:, errors:)
 
-        io.puts "=" * 60
+        io.puts summary_divider(has_failures:, io:)
       end
 
       def print_progress(io:, stats:, errors:, start_time:, status_interval:, skip_reasons: {})
         return unless start_time
 
-        elapsed = (Time.current - start_time).round(1)
         io.puts ""
-        io.puts "=" * 60
-
-        trigger = if status_interval
-                    "every #{status_interval}s (STATUS_INTERVAL)"
-                  elsif Signal.list.key?("INFO")
-                    "Ctrl+T"
-                  else
-                    "SIGUSR1"
-                  end
-
-        io.puts "STATUS (still running) — triggered by #{trigger}"
-        io.puts "-" * 60
-        io.puts "Duration:    #{elapsed}s"
-        io.puts "Processed:   #{stats[:processed]}"
-        io.puts "Succeeded:   #{stats[:succeeded]}"
-        io.puts "Failed:      #{stats[:failed]}"
-        io.puts "Skipped:     #{stats[:skipped]}"
-        print_skip_reasons(io:, skip_reasons:) if skip_reasons.any?
+        io.puts Colors.cyan(DIVIDER, io:)
+        io.puts "#{Colors.cyan("STATUS (still running)", io:)} — triggered by #{status_trigger(status_interval)}"
+        io.puts Colors.dim(SEPARATOR, io:)
+        print_stats(io:, stats:, start_time:, skip_reasons:)
 
         print_errors(io:, errors:) if errors.any?
 
-        io.puts "=" * 60
+        io.puts Colors.cyan(DIVIDER, io:)
         io.puts ""
       end
 
       def print_errors(io:, errors:)
         io.puts ""
-        io.puts "ERRORS:"
-        errors.each do |err|
-          lines = err[:error].to_s.split("\n")
-          io.puts "  #{err[:record]}: #{lines.first}"
-          lines.drop(1).each { |line| io.puts "    #{line}" }
-          err[:backtrace]&.each { |line| io.puts "    #{line}" }
+        io.puts Colors.error("ERRORS:", io:)
+        errors.each { |err| print_single_error(io:, err:) }
+      end
+
+      # --- Private helpers ---
+
+      def print_header_top(io:, shift_class:, dry_run:)
+        io.puts ""
+        io.puts Colors.dim(DIVIDER, io:)
+        io.puts Colors.bold(shift_class.name || "DataShifter::Shift (anonymous)", io:)
+        io.puts Colors.dim("\"#{shift_class.description}\"", io:) if shift_class.description.present?
+        io.puts Colors.dim(SEPARATOR, io:)
+        io.puts "Mode:        #{mode_label(dry_run:, io:)}"
+      end
+
+      def print_header_bottom(io:, status_interval:)
+        status_line = build_status_line(status_interval)
+        io.puts Colors.dim("Status:      #{status_line} for live progress (no abort)", io:) if status_line
+        io.puts Colors.dim(DIVIDER, io:)
+        io.puts ""
+      end
+
+      def print_stats(io:, stats:, start_time:, skip_reasons:)
+        elapsed = (Time.current - start_time).round(1)
+        io.puts "Duration:    #{elapsed}s"
+        io.puts "Processed:   #{stats[:processed]}"
+        io.puts "Succeeded:   #{Colors.green(stats[:succeeded].to_s, io:)}"
+        io.puts "Failed:      #{Colors.red(stats[:failed].to_s, io:)}" if stats[:failed].positive?
+        io.puts "Skipped:     #{Colors.yellow(stats[:skipped].to_s, io:)}" if stats[:skipped].positive?
+        print_skip_reasons(io:, skip_reasons:) if skip_reasons.any?
+      end
+
+      def print_single_error(io:, err:)
+        lines = err[:error].to_s.split("\n")
+        io.puts "  #{Colors.red(err[:record].to_s, io:)}: #{lines.first}"
+        lines.drop(1).each { |line| io.puts "    #{line}" }
+        err[:backtrace]&.each { |line| io.puts Colors.dim("    #{line}", io:) }
+      end
+
+      def mode_label(dry_run:, io:)
+        if dry_run
+          "#{Colors.cyan("DRY RUN", io:)} (no changes will be persisted)"
+        else
+          Colors.warning("LIVE", io:)
         end
       end
 
-      def summary_title(dry_run:, interrupted:)
+      def task_transaction_label(mode)
+        mode == :per_record ? "per-task" : TRANSACTION_MODE_LABELS[mode]
+      end
+
+      def summary_divider(has_failures:, io:)
+        has_failures ? Colors.red(DIVIDER, io:) : Colors.green(DIVIDER, io:)
+      end
+
+      def summary_title(dry_run:, interrupted:, has_failures: false, io: $stdout)
         base = dry_run ? "SUMMARY (DRY RUN)" : "SUMMARY"
-        interrupted ? "#{base} - INTERRUPTED" : base
+        title = interrupted ? "#{base} - INTERRUPTED" : base
+        has_failures ? Colors.error(title, io:) : Colors.success(title, io:)
       end
 
-      def print_interrupt_warning(io:, transaction_mode:, dry_run:)
-        io.puts ""
-        if transaction_mode == :none
-          io.puts "[!] INTERRUPTED: `transaction false` mode was active."
-          io.puts "    Some DB changes may have been applied before interruption."
-          io.puts "    Non-DB side effects (API calls, emails, etc.) are not rolled back."
-          io.puts "    Review the database state before re-running."
-        elsif dry_run
-          io.puts "[!] INTERRUPTED: All DB changes have been rolled back (dry run)."
-          io.puts "    Non-DB side effects (API calls, emails, etc.) are not rolled back."
+      def status_trigger(status_interval)
+        if status_interval
+          "every #{status_interval}s (STATUS_INTERVAL)"
+        elsif Signal.list.key?("INFO")
+          "Ctrl+T"
         else
-          io.puts "[!] INTERRUPTED: DB transaction has been rolled back."
-          io.puts "    No DB changes were persisted."
-          io.puts "    Non-DB side effects (API calls, emails, etc.) are not rolled back."
+          "SIGUSR1"
         end
       end
 
+      def print_interrupt_warning(io:, transaction_mode:, dry_run:)
+        msg = if transaction_mode == :none
+                "`transaction false` mode was active. Some DB changes may have been applied."
+              elsif dry_run
+                "All DB changes have been rolled back (dry run)."
+              else
+                "DB transaction has been rolled back. No DB changes were persisted."
+              end
+        io.puts ""
+        io.puts "#{Colors.warning("[!] INTERRUPTED:", io:)} #{msg}"
+        io.puts "    Non-DB side effects (API calls, emails, etc.) are not rolled back."
+      end
+
       def print_dry_run_instructions(io:, task_name:)
         io.puts ""
-        io.puts "[!] No changes were saved."
+        io.puts Colors.cyan("[!] No changes were saved.", io:)
         return unless task_name.present?
 
         io.puts "To apply these changes, run:"
-        io.puts "    COMMIT=1 rake data:shift:#{task_name}"
+        io.puts "    #{Colors.bold("COMMIT=1 rake data:shift:#{task_name}", io:)}"
       end
 
       def print_continue_from_hint(io:, task_name:, last_successful_id:, dry_run:, transaction_mode:, errors:)
-        return if dry_run
-        return unless transaction_mode == :none
-        return if errors.empty?
-        return unless last_successful_id
-        return unless task_name.present?
+        return if dry_run || transaction_mode != :none || errors.empty? || !last_successful_id || !task_name.present?
 
         io.puts ""
         io.puts "To resume from the last successful record:"
-        io.puts "    CONTINUE_FROM=#{last_successful_id} COMMIT=1 rake data:shift:#{task_name}"
+        io.puts "    #{Colors.bold("CONTINUE_FROM=#{last_successful_id} COMMIT=1 rake data:shift:#{task_name}", io:)}"
       end
 
       def build_status_line(status_interval)

data/lib/data_shifter/shift.rb

@@ -9,6 +9,7 @@ require_relative "internal/record_utils"
 require_relative "internal/progress_bar"
 require_relative "internal/side_effect_guards"
 require_relative "internal/log_deduplicator"
+require_relative "internal/colors"
 
 # Base class for data shifts. Dry-run by default, progress bars, transaction modes, consistent summaries.
 #
@@ -67,6 +68,7 @@ module DataShifter
     class_attribute :_throttle_interval, default: nil
     class_attribute :_allow_external_requests, default: [], instance_accessor: false
     class_attribute :_suppress_repeated_logs, default: nil, instance_accessor: false
+    class_attribute :_task_blocks, default: [], instance_accessor: false
 
     # Internal exception used by skip! to abort the current process_record.
     # Rescued in _process_one; not propagated.
@@ -128,6 +130,21 @@ module DataShifter
         self._suppress_repeated_logs = !!enabled
       end
 
+      # Define a task block to run instead of collection/process_record.
+      # Multiple blocks run in sequence; labels appear in errors and summary.
+      # Example:
+      #   task "Fix user A" do
+      #     User.find(123).update!(...)
+      #   end
+      #   task "Fix user B" do
+      #     User.find(456).update!(...)
+      #   end
+      def task(label = nil, &block)
+        raise ArgumentError, "task requires a block" unless block_given?
+
+        self._task_blocks = (_task_blocks || []).dup + [{ label: label.presence, block: }]
+      end
+
       def run!
         dry_run = Internal::Env.dry_run?
         result = call(dry_run:)
@@ -139,7 +156,11 @@ module DataShifter
     # --- Public API (intentionally exposed to subclasses) ---
 
     def call
-      _for_each_record_in(collection) { |record| process_record(record) }
+      if self.class._task_blocks.any?
+        _run_task_blocks
+      else
+        _for_each_record_in(collection) { |record| process_record(record) }
+      end
     end
 
     def find_exactly!(model, ids)
@@ -163,7 +184,7 @@ module DataShifter
     end
 
     def log(message)
-      puts message
+      puts Internal::Colors.dim(message)
     end
 
     private
@@ -259,11 +280,13 @@ module DataShifter
     # --- Override points ---
 
     def collection
-      raise NotImplementedError, "#{self.class.name}: override `collection`"
+      raise NotImplementedError,
+            "#{self.class.name}: override `collection` (or use one or more `task 'label' do ... end` blocks for targeted shifts)."
     end
 
     def process_record(_record)
-      raise NotImplementedError, "#{self.class.name}: override `process_record`"
+      raise NotImplementedError,
+            "#{self.class.name}: override `process_record` (or use one or more `task 'label' do ... end` blocks for targeted shifts)."
     end
 
     # --- Record iteration ---
@@ -452,5 +475,88 @@ module DataShifter
       # Re-raise to trigger transaction rollback in the wrapping transaction block
       raise Interrupt
     end
+
+    # --- Task block execution ---
+
+    def _run_task_blocks
+      _validate_no_collection_or_process_record_override!
+
+      blocks = self.class._task_blocks
+      _reset_tracking
+      _print_task_header(blocks.size)
+
+      ActiveSupport::IsolatedExecutionState[:_data_shifter_current_run] = self
+      status_proc = proc { ActiveSupport::IsolatedExecutionState[:_data_shifter_current_run]&.send(:_print_progress) }
+      prev_handlers = Internal::SignalHandler.install_status_traps(status_proc)
+
+      begin
+        blocks.each do |entry|
+          _execute_task_block(entry)
+        end
+        fail! "#{@stats[:failed]} task(s) failed" if @errors.any?
+      rescue Interrupt
+        _handle_interrupt
+      ensure
+        ActiveSupport::IsolatedExecutionState.delete(:_data_shifter_current_run)
+        Internal::SignalHandler.restore_status_traps(prev_handlers)
+      end
+    end
+
+    def _validate_no_collection_or_process_record_override!
+      collection_overridden = instance_method_owner(:collection) != DataShifter::Shift
+      process_record_overridden = instance_method_owner(:process_record) != DataShifter::Shift
+
+      return unless collection_overridden || process_record_overridden
+
+      raise ArgumentError,
+            "Cannot use task blocks and override collection or process_record; use one mode or the other."
+    end
+
+    def instance_method_owner(method_name)
+      self.class.instance_method(method_name).owner
+    end
+
+    def _execute_task_block(entry)
+      label = entry[:label]
+      block = entry[:block]
+
+      if _transaction_mode == :per_record && !dry_run?
+        ::ActiveRecord::Base.transaction do
+          _run_single_task_block(label, block)
+        end
+      else
+        _run_single_task_block(label, block)
+      end
+    end
+
+    def _run_single_task_block(label, block)
+      puts Internal::Colors.cyan(">> #{label} <<") if label.present?
+      instance_exec(&block)
+      @stats[:processed] += 1
+      @stats[:succeeded] += 1
+    rescue SkipRecord
+      # skip! already updated @stats[:skipped] and @skip_reasons; continue to next block
+      nil
+    rescue StandardError => e
+      @stats[:failed] += 1
+      identifier = label || "task"
+      error_text = _format_error(e)
+      @errors << { record: identifier, error: error_text, backtrace: e.backtrace&.first(3) }
+      _log_error(identifier, error_text)
+
+      new_message = label.present? ? "#{label}: #{e.message}" : e.message
+      raise e.class, new_message, e.backtrace
+    end
+
+    def _print_task_header(block_count)
+      Internal::Output.print_task_header(
+        io: $stdout,
+        shift_class: self.class,
+        block_count:,
+        dry_run: dry_run?,
+        transaction_mode: _transaction_mode,
+        status_interval: Internal::Env.status_interval_seconds,
+      )
+    end
   end
 end

data/lib/data_shifter/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module DataShifter
-  VERSION = "0.2.0"
+  VERSION = "0.3.0"
 end

data/lib/generators/data_shift_generator.rb

@@ -5,6 +5,7 @@
 # Usage:
 #   rails g data_shift backfill_users
 #   rails g data_shift backfill_users --model=User
+#   rails g data_shift fix_order_1234 --task
 #
 class DataShiftGenerator < Rails::Generators::NamedBase
   class_option :model,
@@ -17,6 +18,11 @@ class DataShiftGenerator < Rails::Generators::NamedBase
                default: false,
                desc: "Generate RSpec file"
 
+  class_option :task,
+               type: :boolean,
+               default: false,
+               desc: "Generate a task-based shift (uses task blocks instead of collection/process_record)"
+
   def check_for_naming_conflict
     underscored_name = name.underscore
 
@@ -44,6 +50,29 @@ class DataShiftGenerator < Rails::Generators::NamedBase
     model_name_raw = options[:model].to_s.strip
     @model_name = model_name_raw.present? ? model_name_raw.underscore.singularize.camelize : nil
 
+    if options[:task]
+      _create_task_shift_file(underscored_name)
+    else
+      _create_standard_shift_file(underscored_name)
+    end
+  end
+
+  def create_spec_file
+    return unless options[:spec]
+    return unless rspec_enabled?
+
+    underscored_name = name.underscore
+
+    if options[:task]
+      _create_task_spec_file(underscored_name)
+    else
+      _create_standard_spec_file(underscored_name)
+    end
+  end
+
+  private
+
+  def _create_standard_shift_file(underscored_name)
     collection_body = if @model_name.present?
                         "#{@model_name}.all"
                       else
@@ -76,14 +105,34 @@ class DataShiftGenerator < Rails::Generators::NamedBase
     RUBY
   end
 
-  def create_spec_file
-    return unless options[:spec]
-    return unless rspec_enabled?
+  def _create_task_shift_file(underscored_name)
+    model_comment = @model_name.present? ? "# #{@model_name}.find(...).update!(...)" : "# Model.find(...).update!(...)"
+    task_label = @class_name.underscore.humanize
 
-    underscored_name = name.underscore
-    record_arg = @model_name.present? ? @model_name.underscore : "record"
+    create_file "lib/data_shifts/#{@timestamp}_#{underscored_name}.rb", <<~RUBY
+      # frozen_string_literal: true
+
+      #   rake data:shift:#{underscored_name}          # Dry run (default)
+      #   COMMIT=1 rake data:shift:#{underscored_name} # Apply changes
+
+      module DataShifts
+        class #{@class_name} < DataShifter::Shift
+          description "TODO: Describe this shift"
+
+          transaction true # or :per_record for per-task transactions
 
+          task "#{task_label}" do
+            #{model_comment}
+          end
+        end
+      end
+    RUBY
+  end
+
+  def _create_standard_spec_file(underscored_name)
+    record_arg = @model_name.present? ? @model_name.underscore : "record"
     model_for_change = @model_name.present? ? @model_name : "Model"
+
     create_file "spec/lib/data_shifts/#{underscored_name}_spec.rb", <<~RUBY
       # frozen_string_literal: true
 
@@ -98,28 +147,53 @@ class DataShiftGenerator < Rails::Generators::NamedBase
         # Set up test records as needed
         # let(:#{record_arg}) { create(:#{record_arg}) }
 
-        describe "dry run" do
-          it "does not persist changes" do
-            expect do
-              result = run_data_shift(described_class, dry_run: true)
-              expect(result).to be_ok
-            end.not_to change(#{model_for_change}, :count)
+        context "when dry run" do
+          subject(:result) { run_data_shift(described_class, dry_run: true) }
+
+          it "succeeds without persisting changes" do
+            expect { result }.not_to change(#{model_for_change}, :count)
+            expect(result).to be_ok
           end
         end
 
-        describe "commit" do
+        context "when commit" do
+          subject(:result) { run_data_shift(described_class, commit: true) }
+
           it "applies changes" do
-            expect do
-              result = run_data_shift(described_class, commit: true)
-              expect(result).to be_ok
-            end.to change(#{model_for_change}, :count)
+            expect { result }.to change(#{model_for_change}, :count)
+            expect(result).to be_ok
           end
         end
       end
     RUBY
   end
 
-  private
+  def _create_task_spec_file(underscored_name)
+    create_file "spec/lib/data_shifts/#{underscored_name}_spec.rb", <<~RUBY
+      # frozen_string_literal: true
+
+      require "rails_helper"
+      require "data_shifter/spec_helper"
+
+      RSpec.describe DataShifts::#{@class_name} do
+        include DataShifter::SpecHelper
+
+        before { allow($stdout).to receive(:puts) }
+
+        context "when dry run" do
+          subject(:result) { run_data_shift(described_class, dry_run: true) }
+
+          it { is_expected.to be_ok }
+        end
+
+        context "when commit" do
+          subject(:result) { run_data_shift(described_class, commit: true) }
+
+          it { is_expected.to be_ok }
+        end
+      end
+    RUBY
+  end
 
   def rspec_enabled?
     # Check if rspec-rails is available and configured as the test framework

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: data_shifter
 version: !ruby/object:Gem::Version
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors:
 - Kali Donovan
@@ -116,6 +116,7 @@ files:
 - lib/data_shifter.rb
 - lib/data_shifter/configuration.rb
 - lib/data_shifter/errors.rb
+- lib/data_shifter/internal/colors.rb
 - lib/data_shifter/internal/env.rb
 - lib/data_shifter/internal/log_deduplicator.rb
 - lib/data_shifter/internal/output.rb