Add class-level progress macro for Migration

Lets users declare `progress eta: true` once at the class level
instead of passing `eta: true` on every `report` call. The `eta`
option moves from ProgressReporter#report to the constructor,
and Migration forwards class-level options automatically.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: MatheusRich

README.md

@@ -180,10 +180,26 @@ end
 It accepts a percentage (0–100) and throttles output, so it's safe to call on
 every iteration. At 100%, it shows the total elapsed time.
 
-Pass `eta: true` to show estimated time remaining:
+Use `progress eta: true` at the class level to show estimated time remaining:
 
 ```ruby
-progress.report(processed.to_f / total * 100, eta: true)
+class BackfillUsernames < DataCustoms::Migration
+  progress eta: true
+
+  def up
+    scope = User.where(username: nil)
+    total = scope.count
+    processed = 0
+
+    find_each(scope) do |user|
+      user.update!(username: "guest_#{user.id}")
+      processed += 1
+      progress.report(processed.to_f / total * 100)
+    end
+  end
+
+  # ...
+end
 ```
 
 ```

lib/data_customs/migration.rb

@@ -5,6 +5,14 @@ class Migration
     DEFAULT_BATCH_SIZE = 1000
     DEFAULT_THROTTLE = 0.01
 
+    def self.progress(**options)
+      @progress_options = options
+    end
+
+    def self.progress_options
+      @progress_options || {}
+    end
+
     def self.run(...)
       ActiveRecord::Base.transaction do
         new(...).run
@@ -29,7 +37,7 @@ def run
 
     def with_progress_reporter(&block)
       ProgressOutput.wrap do |output|
-        @_progress = ProgressReporter.new(output)
+        @_progress = ProgressReporter.new(output, **self.class.progress_options)
         block.call
       end
     end

lib/data_customs/progress_reporter.rb

@@ -6,12 +6,13 @@ class ProgressReporter
     PRINT_INTERVAL = 1 # seconds
     ETA_MIN_ELAPSED = 2 # seconds before showing ETA
 
-    def initialize(output)
+    def initialize(output, eta: false)
       @output = ThrottledOutput.new(output, interval: PRINT_INTERVAL)
       @started_at = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      @eta = eta
     end
 
-    def report(percentage, eta: false)
+    def report(percentage)
       percentage = percentage.floor.clamp(0, 100)
       line = bar(percentage)
 
@@ -22,7 +23,7 @@ def report(percentage, eta: false)
         return
       end
 
-      if eta && percentage > 0
+      if @eta && percentage > 0
         elapsed = Process.clock_gettime(Process::CLOCK_MONOTONIC) - @started_at
         if elapsed >= ETA_MIN_ELAPSED
           remaining = elapsed / percentage * (100 - percentage)

spec/data_customs/migration_spec.rb

@@ -132,7 +132,11 @@ def verify! = nil
     end
 
     it "shows 'estimating...' before enough time has elapsed" do
-      migration = build_migration { progress.report(50, eta: true) }
+      migration = Class.new(DataCustoms::Migration) do
+        progress eta: true
+        define_method(:up) { progress.report(50) }
+        def verify! = nil
+      end
 
       expect { migration.run }.to output(
         /Progress: .+ 50% \(estimating\.\.\.\)\n/
@@ -144,9 +148,13 @@ def verify! = nil
       # ProgressReporter.new, report(25) eta + throttle, report(50) eta + throttle
       allow(Process).to receive(:clock_gettime).and_return(now, now, now, now + 5.0, now + 5.0)
 
-      migration = build_migration do
-        progress.report(25, eta: true)
-        progress.report(50, eta: true)
+      migration = Class.new(DataCustoms::Migration) do
+        progress eta: true
+        define_method(:up) do
+          progress.report(25)
+          progress.report(50)
+        end
+        def verify! = nil
       end
 
       expect { migration.run }.to output(
@@ -170,9 +178,13 @@ def verify! = nil
     end
 
     it "does not show ETA at 0% or 100%" do
-      migration = build_migration do
-        progress.report(0, eta: true)
-        progress.report(100, eta: true)
+      migration = Class.new(DataCustoms::Migration) do
+        progress eta: true
+        define_method(:up) do
+          progress.report(0)
+          progress.report(100)
+        end
+        def verify! = nil
       end
 
       expect { migration.run }.to output(
@@ -183,6 +195,26 @@ def verify! = nil
     end
   end
 
+  describe ".progress" do
+    it "configures ETA at the class level" do
+      now = Process.clock_gettime(Process::CLOCK_MONOTONIC)
+      allow(Process).to receive(:clock_gettime).and_return(now, now, now, now + 5.0, now + 5.0)
+
+      migration = Class.new(DataCustoms::Migration) do
+        progress eta: true
+        define_method(:up) do
+          progress.report(25)
+          progress.report(50)
+        end
+        def verify! = nil
+      end
+
+      expect { migration.run }.to output(
+        /Progress: .+ 50% \(\d+s left\)\n/
+      ).to_stdout
+    end
+  end
+
   describe "helpers" do
     it "batches records" do
       3.times { |i| TestUser.create!(name: "User #{i}") }