sidekiq-tasks 1.1.0 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 6f83fac86d2f51190ad4a2a5df9bee05f0f06fb5329b12895cd59f9dd253bb4b
-  data.tar.gz: 3955f36ff3bceab435c4e862fd1c2110c3b7e2c9c315a895a1354cc0acaa8f26
+  metadata.gz: 4298eb4b8e1e6e6a3136940f0dc23aba41777faa48046aa9f6e8011656b0f1c3
+  data.tar.gz: 24b88855eea1cb680d68e553ea33b3727dbc7840de45e201fbce7c835750d3b3
 SHA512:
-  metadata.gz: 70278e1ffc5110edaeebcf2f275cc3942a683fcf60ebf8154810c5a69f0eb27335ee333cccda10d3f266c8978078de826abd9c58bc532e850e844f5d490843e3
-  data.tar.gz: a951353d439a6a0e21b643a55e20bae9e695ff569f7d8c6e46c15c18599528c1f1675c2833869ccf474529b45264fd491c785646f729151d7bf8867596d0b90d
+  metadata.gz: fc95a609c74c0e0cdf36b40cdaa052e0049ee13f368ea34541bab6c60c163b76aa064cf16f2d7004a69c577d123ea5617f09c1dd933f2fa53c2756c1ffcfba85
+  data.tar.gz: 44dcf4152c96020b7001c72333d331fc063e9c10e28decd60c1c9d7f6455037ebae10700571e2cb84800088b0220e09cdb16c0842089c987d656b146cb58c3ef

data/.rubocop.yml

@@ -26,6 +26,7 @@ Metrics/MethodLength:
 Metrics/ParameterLists:
   Exclude:
     - spec/**/*
+    - lib/sidekiq/tasks/task_metadata.rb
 
 Metrics/PerceivedComplexity:
   Exclude:
@@ -41,6 +42,9 @@ Naming/MemoizedInstanceVariableName:
 Style/Documentation:
   Enabled: false
 
+Style/EmptyMethod:
+  EnforcedStyle: expanded
+
 Style/FrozenStringLiteralComment:
   Enabled: false
 

data/CHANGELOG.md

@@ -1,5 +1,23 @@
 ## Changelog
 
+### [1.2.0] - 2026-10-28
+
+- Add per-task `sidekiq_options` magic comment to override the global options at enqueue time, displayed on the task detail page.
+- Render tasks with an invalid magic comment as a broken state in the web UI instead of crashing the tasks list.
+- Validate the values of the supported keys of the `sidekiq_options` magic comment, other keys are passed as is to Sidekiq.
+- Add dry run mode: tasks with the `sidekiq-tasks:dry_run` magic comment get a "Dry run" checkbox, checked by default, and read it with `Sidekiq::Tasks.dry_run?`.
+- Add structured execution reports (`Sidekiq::Tasks.report`) displayed in the task history.
+- Add a configurable `report_max_bytes` option (default: 64 KB, maximum: 1 MB) bounding the report size. The Redis storage also keeps the reports of a task history within 10 MB.
+- Fix detection of stacked magic comments placed before a `desc` or a `namespace`.
+- Fix magic comments leaking to a neighbour task or a similarly named namespace, and support nested namespaces.
+- Magic comments must now be alone on their line, right above the `task`, `desc` or `namespace` call, with no blank line in between.
+- Escape task arguments, enqueuing user and error message in the task history.
+- Fix execution times lost in the history when the job starts before the history entry is stored.
+
+### [1.1.1] - 2026-04-12
+
+- Transfer repository ownership to Capsens organization.
+
 ### [1.1.0] - 2026-04-08
 
 - Search tasks by description in addition to name.

data/LICENSE.txt

@@ -1,6 +1,6 @@
 The MIT License (MIT)
 
-Copyright (c) 2025 Victor
+Copyright (c) 2025 Capsens
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

data/README.md

@@ -1,8 +1,8 @@
 # Sidekiq::Tasks
 
-[![CI Status](https://github.com/victorauthiat/sidekiq-tasks/actions/workflows/ci.yml/badge.svg)](https://github.com/victorauthiat/sidekiq-tasks/actions/workflows/ci.yml)
-[![Maintainability](https://qlty.sh/gh/VictorAuthiat/projects/sidekiq-tasks/maintainability.svg)](https://qlty.sh/gh/VictorAuthiat/projects/sidekiq-tasks)
-[![Code Coverage](https://qlty.sh/gh/VictorAuthiat/projects/sidekiq-tasks/coverage.svg)](https://qlty.sh/gh/VictorAuthiat/projects/sidekiq-tasks)
+[![CI Status](https://github.com/CapSens/sidekiq-tasks/actions/workflows/ci.yml/badge.svg)](https://github.com/CapSens/sidekiq-tasks/actions/workflows/ci.yml)
+[![Maintainability](https://qlty.sh/gh/CapSens/projects/sidekiq-tasks/maintainability.svg)](https://qlty.sh/gh/CapSens/projects/sidekiq-tasks)
+[![Code Coverage](https://qlty.sh/gh/CapSens/projects/sidekiq-tasks/coverage.svg)](https://qlty.sh/gh/CapSens/projects/sidekiq-tasks)
 
 > A [Sidekiq](https://github.com/sidekiq/sidekiq) extension for task management.
 
@@ -197,6 +197,23 @@ end
 
 All standard [Sidekiq job options](https://github.com/sidekiq/sidekiq/wiki/Advanced-Options#jobs) are supported.
 
+### Per-task overrides via magic comment
+
+You can override `sidekiq_options` for a single Rake task with the `sidekiq-tasks:sidekiq_options` magic comment placed right before the task:
+
+```ruby
+# sidekiq-tasks:enable
+# sidekiq-tasks:sidekiq_options: queue: low
+task :generate_sales_report do
+  # ...
+end
+```
+
+Placed before a namespace, it applies to all its tasks, and a task level comment takes precedence.
+
+The value is parsed as inline YAML and merged on top of the global `config.sidekiq_options` at enqueue time. Supported keys: `queue`, `retry`, `retry_for`, `dead`, `backtrace`, `pool`, `tags`.
+These keys are validated: an invalid value (e.g. `retry: abc`) displays the task as broken in the web interface, and it cannot be enqueued. Other keys are passed as is to Sidekiq, e.g. middleware options such as sidekiq-unique-jobs `lock: until_executed`.
+
 You can also override the `enqueue_task` method to implement your own enqueuing logic for your strategy:
 
 ```ruby
@@ -243,6 +260,85 @@ end
 
 You can also use a custom storage backend. See the [Custom Storage Guide](docs/custom_storage.md) for more details.
 
+## Dry run and reports
+
+Inside a task, `Sidekiq::Tasks.dry_run?` tells whether the task runs in dry run mode and `Sidekiq::Tasks.report` gives access to a structured report:
+
+```ruby
+# sidekiq-tasks:enable
+# sidekiq-tasks:dry_run
+task :sync_users => :environment do
+  User.find_each do |user|
+    Sync.call(user) unless Sidekiq::Tasks.dry_run?
+    Sidekiq::Tasks.report.increment(:success)
+  rescue => e
+    Sidekiq::Tasks.report.increment(:errors)
+    Sidekiq::Tasks.report.add(:failed, id: user.id, email: user.email, error: e.message)
+  end
+end
+```
+
+Both are shortcuts for `Sidekiq::Tasks.current_run.dry_run?` and `Sidekiq::Tasks.current_run.report`.
+
+### Dry run
+
+Dry run mode lets a user check what a task would do before running it for real, typically together with a [report](#report) of the rows it would process.
+
+**What the gem does:**
+
+- detects tasks declaring the `sidekiq-tasks:dry_run` magic comment. Like `enable`, it can be placed before the task, its `desc` or its `namespace`, stacked with other magic comments,
+- displays a **Dry run** checkbox on these tasks, checked by default: the user has to uncheck it to execute the task for real. Other tasks display a warning stating that they will be executed for real,
+- passes the choice to the Sidekiq job, where `Sidekiq::Tasks.dry_run?` returns it,
+- flags dry runs with a badge in the task history.
+
+**What the developer does:**
+
+- adds the `sidekiq-tasks:dry_run` magic comment to the tasks that support dry run mode,
+- skips every side effect when `Sidekiq::Tasks.dry_run?` is `true`: database writes, emails, API calls, file uploads, enqueued jobs...,
+- keeps the rest of the task running (queries, validations, computations), so that the dry run reflects what the real run would do,
+- optionally fills the report, so that the dry run result shows up in the web interface.
+
+> [!WARNING]
+> The gem never skips anything by itself: a task declaring the magic comment without checking `Sidekiq::Tasks.dry_run?` executes all of its side effects, even when the checkbox is checked.
+
+Outside of the web interface (e.g. `rake sync_users` in a terminal), `dry_run?` is `false`.
+Both `dry_run?` and `report` are optional: a task can use the report without dry run mode, and existing tasks keep working unchanged.
+
+### Report
+
+- `report[:key] = value` sets a summary value.
+- `report.increment(:key)` increments a counter.
+- `report.add(:key, item)` adds an item (a scalar or a flat Hash) to a list. Hash items are displayed as a table whose columns are the hash keys.
+
+Keys are free: use as many lists as needed (`:synced`, `:skipped`, `:failed`...). Values are displayed in the history table, lists in a collapsible section below it (the latest execution is expanded). The report is stored whether the task runs in dry run mode or not, and also when it fails.
+
+Numbers, booleans and `nil` are kept as is, other values are converted to strings: pass the useful attributes of an object (`{id: user.id, email: user.email}`) rather than the object itself, and prefer one list per key to nested structures.
+
+The report is stored with the execution history, so its size is bounded by `report_max_bytes` (default: 64 KB, maximum: 1 MB):
+
+```ruby
+Sidekiq::Tasks.configure do |config|
+  config.report_max_bytes = 256 * 1024
+end
+```
+
+- a value above the maximum does not prevent the application from starting: it is lowered to the maximum and a warning is logged,
+- when the report exceeds it, the last items of the longest lists are dropped and the report is flagged as truncated in the web interface, the counts remain exact,
+- with the Redis storage, the reports of a task history never exceed 10 MB: with a large `history_limit`, the size of each report is lowered accordingly (`10 MB / history_limit`),
+- strings are truncated to 255 characters, so that a single long message does not fill the whole report,
+- at most 50 values, 50 lists and 50 keys per item, guarding against keys built from the data,
+- while the task runs, items stop being kept beyond 4 times the report size, so that the worker memory stays bounded.
+
+The report never makes a task fail. Outside of a Sidekiq::Tasks job, it is printed as JSON when the process exits.
+
+> [!TIP]
+> For large or complex reports, prefer a database storage (see the [Custom Storage Guide](docs/custom_storage.md)) over Redis: reports are kept in the database instead of Redis memory, and are not lowered by the 10 MB budget of the Redis storage.
+
+> [!NOTE]
+> Custom strategies enable dry run mode by building their metadata with `dry_run: true`.
+> Those overriding `enqueue_task` then receive a `dry_run: true` keyword argument, to pass to `Sidekiq::Tasks::Job` as its third argument.
+> Custom storages display the dry run badge and reports by implementing `store_dry_run` and `store_execution_report`, see the [Custom Storage Guide](docs/custom_storage.md).
+
 ## Current user
 
 You can configure a `current_user` proc to track who enqueued each task.
@@ -267,7 +363,7 @@ To install this gem onto your local machine, run `bundle exec rake install`. To
 
 ## Contributing
 
-Bug reports and pull requests are welcome on GitHub at https://github.com/victorauthiat/sidekiq-tasks. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/victorauthiat/sidekiq-tasks/blob/master/CODE_OF_CONDUCT.md).
+Bug reports and pull requests are welcome on GitHub at https://github.com/CapSens/sidekiq-tasks. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/CapSens/sidekiq-tasks/blob/master/CODE_OF_CONDUCT.md).
 
 ## License
 
@@ -275,4 +371,4 @@ The gem is available as open source under the terms of the [MIT License](https:/
 
 ## Code of Conduct
 
-Everyone interacting in the Sidekiq::Tasks project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/victorauthiat/sidekiq-tasks/blob/master/CODE_OF_CONDUCT.md).
+Everyone interacting in the Sidekiq::Tasks project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/CapSens/sidekiq-tasks/blob/master/CODE_OF_CONDUCT.md).

data/docs/custom_storage.md

@@ -7,7 +7,7 @@ This guide walks you through implementing a custom storage backend using ActiveR
 ```bash
 rails generate model TaskExecution \
   task_name:string:index \
-  jid:string:index \
+  jid:string:uniq \
   args:jsonb \
   enqueued_at:datetime \
   executed_at:datetime \
@@ -38,22 +38,16 @@ class ActiveRecordStorage < Sidekiq::Tasks::Storage::Base
   end
 
   def store_enqueue(jid, args, user: nil)
-    TaskExecution.create!(
-      task_name: task_name,
-      jid: jid,
-      args: args,
-      enqueued_at: Time.now,
-      user: user
-    )
+    TaskExecution.create_or_find_by!(jid: jid).update!(task_name: task_name, args: args, enqueued_at: Time.now, user: user)
   end
 
   def store_execution(jid, time_key)
-    TaskExecution.find_by(jid: jid)&.update!(time_key => Time.now)
+    TaskExecution.create_or_find_by!(jid: jid).update!(time_key => Time.now)
   end
 
   def store_execution_error(jid, error)
     message = truncate_message("#{error.class}: #{error.message}", ERROR_MESSAGE_MAX_LENGTH)
-    TaskExecution.find_by(jid: jid)&.update!(error: message)
+    TaskExecution.create_or_find_by!(jid: jid).update!(error: message)
   end
 end
 
@@ -80,9 +74,48 @@ The `history` method must return an array of hashes with the following keys:
 | `"error"`       | String \| nil | Error message if execution failed    |
 | `"user"`        | Hash \| nil   | User who enqueued the task           |
 
+Two optional keys are displayed when present:
+
+| Key         | Type          | Description                                                  |
+|-------------|---------------|--------------------------------------------------------------|
+| `"dry_run"` | Boolean       | Whether the task was executed in dry run mode                |
+| `"report"`  | Hash \| nil   | The execution report, see `Sidekiq::Tasks::Report#to_h`      |
+
+They are stored through `store_dry_run(jid)` and `store_execution_report(jid, report)`, which do nothing by default.
+Override them to support dry run badges and reports, e.g. with `dry_run:boolean` and `report:jsonb` columns, also added to the `history` select:
+
+```ruby
+def store_dry_run(jid)
+  TaskExecution.create_or_find_by!(jid: jid).update!(dry_run: true)
+end
+
+def store_execution_report(jid, report)
+  TaskExecution.create_or_find_by!(jid: jid).update!(report: report)
+end
+```
+
+Reports are bounded by `config.report_max_bytes` (default: 64 KB, maximum: 1 MB). The 10 MB budget of the Redis storage for the reports of a task history does not apply to custom storages.
+
 ## Migrating from Redis
 
-After switching to a custom storage, you can clean up the old Redis history:
+To keep the history, add this one-off task in `lib/tasks/sidekiq_tasks_copy_redis_history.rake`, run it once after switching to the custom storage with `bin/rails sidekiq_tasks:copy_redis_history`, then delete it:
+
+```ruby
+namespace :sidekiq_tasks do
+  desc "Copy the sidekiq-tasks history from Redis to the database"
+  task copy_redis_history: :environment do
+    Sidekiq.redis { |conn| conn.keys("task:*:history") }.each do |history_key|
+      task_name = history_key.delete_prefix("task:").delete_suffix(":history")
+
+      Sidekiq::Tasks::Storage::Redis.new(task_name).history.each do |entry|
+        TaskExecution.create_or_find_by!(jid: entry["jid"]).update!(entry.slice(*TaskExecution.column_names))
+      end
+    end
+  end
+end
+```
+
+Then clean up the old Redis history:
 
 ```bash
 redis-cli --scan --pattern "task:*" | xargs redis-cli del

data/lib/sidekiq/tasks/config.rb

@@ -1,3 +1,5 @@
+require "sidekiq"
+
 module Sidekiq
   module Tasks
     class Config
@@ -19,9 +21,14 @@ module Sidekiq
 
       DEFAULT_HISTORY_LIMIT = 10
 
+      DEFAULT_REPORT_MAX_BYTES = 64 * 1024
+
+      REPORT_MAX_BYTES_LIMIT = 1024 * 1024
+
       include Sidekiq::Tasks::Validations
 
-      attr_reader :strategies, :sidekiq_options, :authorization, :history_limit, :current_user, :storage
+      attr_reader :strategies, :sidekiq_options, :authorization, :history_limit, :current_user, :storage,
+                  :report_max_bytes
 
       def initialize
         @sidekiq_options = DEFAULT_SIDEKIQ_OPTIONS
@@ -30,18 +37,12 @@ module Sidekiq
         @authorization = ->(_env) { true }
         @history_limit = DEFAULT_HISTORY_LIMIT
         @current_user = nil
+        @report_max_bytes = DEFAULT_REPORT_MAX_BYTES
       end
 
       # @see https://github.com/sidekiq/sidekiq/wiki/Advanced-Options#jobs
       def sidekiq_options=(options)
-        validate_class!(options, [Hash], "sidekiq_options")
-        validate_hash_option!(options, :queue, [String])
-        validate_hash_option!(options, :retry, [NilClass, TrueClass, FalseClass, Integer])
-        validate_hash_option!(options, :retry_for, [NilClass, Integer, Float])
-        validate_hash_option!(options, :dead, [NilClass, TrueClass, FalseClass])
-        validate_hash_option!(options, :backtrace, [NilClass, TrueClass, FalseClass, Integer])
-        validate_hash_option!(options, :pool, [NilClass, String])
-        validate_hash_option!(options, :tags, [NilClass, Array])
+        Sidekiq::Tasks::SidekiqOptionsValidator.validate!(options)
 
         @sidekiq_options = options
       end
@@ -66,6 +67,14 @@ module Sidekiq
         @history_limit = limit
       end
 
+      def report_max_bytes=(max_bytes)
+        validate_class!(max_bytes, [Integer], "report_max_bytes")
+
+        raise Sidekiq::Tasks::ArgumentError, "'report_max_bytes' must be greater than 0" if max_bytes <= 0
+
+        @report_max_bytes = bounded(max_bytes, REPORT_MAX_BYTES_LIMIT, "report_max_bytes")
+      end
+
       def authorization=(authorization_proc)
         validate_class!(authorization_proc, [Proc], "authorization")
 
@@ -77,6 +86,16 @@ module Sidekiq
 
         @current_user = current_user_proc
       end
+
+      private
+
+      # A too large value never prevents the application from starting: it is lowered to the limit.
+      def bounded(value, limit, name)
+        return value if value <= limit
+
+        Sidekiq.logger.warn("[sidekiq-tasks] '#{name}' (#{value}) exceeds the maximum, using #{limit}")
+        limit
+      end
     end
   end
 end

data/lib/sidekiq/tasks/job.rb

@@ -9,10 +9,11 @@ module Sidekiq
 
       # @param name [String] The name of the task to execute.
       # @param args [Hash] The arguments to pass to the task.
+      # @param dry_run [Boolean] Whether the task is executed in dry run mode.
       # @raise [Sidekiq::Tasks::TaskNotFoundError] If the task is not found.
-      def perform(name, args)
+      def perform(name, args, dry_run = false) # rubocop:disable Style/OptionalBooleanParameter -- Sidekiq args are positional
         symbolized_args = JSON.parse(args, symbolize_names: true)
-        Sidekiq::Tasks.tasks.find_by!(name: name).execute(symbolized_args, jid: jid)
+        Sidekiq::Tasks.tasks.find_by!(name: name).execute(symbolized_args, jid: jid, dry_run: dry_run)
       end
     end
   end

data/lib/sidekiq/tasks/magic_comments/comment.rb

@@ -0,0 +1,28 @@
+module Sidekiq
+  module Tasks
+    module MagicComments
+      class Comment
+        VALID_LOCATIONS = %i[task desc namespace].freeze
+
+        attr_reader :name, :raw_value, :location
+
+        def initialize(name:, location:, raw_value: nil)
+          @name = name.to_s
+          @raw_value = raw_value
+          @location = location
+
+          validate!
+        end
+
+        private
+
+        def validate!
+          return if VALID_LOCATIONS.include?(location)
+
+          raise Sidekiq::Tasks::ArgumentError,
+                "'location' must be one of #{VALID_LOCATIONS.inspect} but received #{location.inspect}"
+        end
+      end
+    end
+  end
+end

data/lib/sidekiq/tasks/magic_comments/comments.rb

@@ -0,0 +1,31 @@
+module Sidekiq
+  module Tasks
+    module MagicComments
+      class Comments
+        include Enumerable
+
+        def initialize(list = [])
+          @list = list
+        end
+
+        def each(&block)
+          @list.each(&block)
+        end
+
+        def any?(name)
+          @list.any? { |comment| comment.name == name.to_s }
+        end
+
+        def fetch(name, default: nil)
+          comment = @list.find { |c| c.name == name.to_s }
+          return default unless comment
+
+          handler = Registry.lookup(name)
+          return comment.raw_value unless handler
+
+          handler.cast(comment.raw_value)
+        end
+      end
+    end
+  end
+end

data/lib/sidekiq/tasks/magic_comments/handlers/base.rb

@@ -0,0 +1,26 @@
+module Sidekiq
+  module Tasks
+    module MagicComments
+      module Handlers
+        class Base
+          # Returns the magic comment token used after `sidekiq-tasks:`.
+          #
+          # @abstract Subclasses must implement this method.
+          # @return [String]
+          def self.name_token
+            raise Sidekiq::Tasks::NotImplementedError, "Handler must implement .name_token"
+          end
+
+          # Casts the raw string value extracted from the magic comment into a typed value.
+          #
+          # @abstract Subclasses must implement this method.
+          # @param raw_value [String, NilClass]
+          # @return [Object]
+          def self.cast(_raw_value)
+            raise Sidekiq::Tasks::NotImplementedError, "Handler must implement .cast"
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sidekiq/tasks/magic_comments/handlers/disable.rb

@@ -0,0 +1,17 @@
+module Sidekiq
+  module Tasks
+    module MagicComments
+      module Handlers
+        class Disable < Base
+          def self.name_token
+            "disable"
+          end
+
+          def self.cast(_raw_value)
+            true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sidekiq/tasks/magic_comments/handlers/dry_run.rb

@@ -0,0 +1,17 @@
+module Sidekiq
+  module Tasks
+    module MagicComments
+      module Handlers
+        class DryRun < Base
+          def self.name_token
+            "dry_run"
+          end
+
+          def self.cast(_raw_value)
+            true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sidekiq/tasks/magic_comments/handlers/enable.rb

@@ -0,0 +1,17 @@
+module Sidekiq
+  module Tasks
+    module MagicComments
+      module Handlers
+        class Enable < Base
+          def self.name_token
+            "enable"
+          end
+
+          def self.cast(_raw_value)
+            true
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sidekiq/tasks/magic_comments/handlers/sidekiq_options.rb

@@ -0,0 +1,32 @@
+require "yaml"
+
+module Sidekiq
+  module Tasks
+    module MagicComments
+      module Handlers
+        class SidekiqOptions < Base
+          def self.name_token
+            "sidekiq_options"
+          end
+
+          def self.cast(raw_value)
+            return {} if raw_value.nil? || raw_value.strip.empty?
+
+            options = parse_yaml(raw_value)
+            # Unknown keys are passed as is to Sidekiq, for middleware options such as sidekiq-unique-jobs locks.
+            Sidekiq::Tasks::SidekiqOptionsValidator.validate!(options, allow_partial: true)
+            options
+          end
+
+          def self.parse_yaml(raw_value)
+            YAML.safe_load("{#{raw_value}}", permitted_classes: [Symbol], symbolize_names: true)
+          rescue Psych::SyntaxError => e
+            raise Sidekiq::Tasks::ArgumentError,
+                  "'sidekiq_options' magic comment is not valid YAML: #{e.message}"
+          end
+          private_class_method :parse_yaml
+        end
+      end
+    end
+  end
+end

data/lib/sidekiq/tasks/magic_comments/registration.rb

@@ -0,0 +1,11 @@
+require_relative "registry"
+require_relative "handlers/base"
+require_relative "handlers/enable"
+require_relative "handlers/disable"
+require_relative "handlers/dry_run"
+require_relative "handlers/sidekiq_options"
+
+Sidekiq::Tasks::MagicComments::Registry.register(Sidekiq::Tasks::MagicComments::Handlers::Enable)
+Sidekiq::Tasks::MagicComments::Registry.register(Sidekiq::Tasks::MagicComments::Handlers::Disable)
+Sidekiq::Tasks::MagicComments::Registry.register(Sidekiq::Tasks::MagicComments::Handlers::SidekiqOptions)
+Sidekiq::Tasks::MagicComments::Registry.register(Sidekiq::Tasks::MagicComments::Handlers::DryRun)

data/lib/sidekiq/tasks/magic_comments/registry.rb

@@ -0,0 +1,19 @@
+module Sidekiq
+  module Tasks
+    module MagicComments
+      module Registry
+        @handlers = {}
+
+        class << self
+          def register(handler)
+            @handlers[handler.name_token.to_s] = handler
+          end
+
+          def lookup(name)
+            @handlers[name.to_s]
+          end
+        end
+      end
+    end
+  end
+end

data/lib/sidekiq/tasks/magic_comments/scanner.rb

@@ -0,0 +1,83 @@
+require "prism"
+
+module Sidekiq
+  module Tasks
+    module MagicComments
+      # A magic comment only applies to the task, desc or namespace call right below it.
+      class Scanner
+        MAGIC_COMMENT_REGEX = /\A#\s*sidekiq-tasks:([a-z_]+)(?::\s*(.+?))?\s*\z/
+
+        def initialize
+          @comments_by_file = {}
+        end
+
+        # @return [Comments] From the task to the outermost namespace, so that the closest comment wins.
+        def scan(task)
+          file, task_line = task.locations.first.split(":")
+          @comments_by_file[file] ||= comments_by_task_line(file)
+
+          Comments.new(@comments_by_file[file].fetch(task_line.to_i, []))
+        end
+
+        private
+
+        def comments_by_task_line(file)
+          parse_result = Prism.parse(read_file(file))
+          comment_lines =
+            parse_result
+            .comments
+            .reject(&:trailing?)
+            .to_h { |comment| [comment.location.start_line, comment.slice] }
+
+          annotated_calls_by_task_line(parse_result.value).transform_values do |annotated_calls|
+            annotated_calls.flat_map { |call, location| magic_comments_above(call, location, comment_lines) }
+          end
+        end
+
+        def read_file(file)
+          File.read(file)
+        rescue Errno::ENOENT
+          raise Sidekiq::Tasks::ArgumentError, "File '#{file}' not found"
+        end
+
+        # Keyed by the line where the task call starts, as recorded by Rake.
+        def annotated_calls_by_task_line(node, namespace_calls = [], annotated_calls = {})
+          [nil, *node.compact_child_nodes].each_cons(2) do |previous_child, child|
+            if rake_call?(child, :task)
+              annotated_calls[child.location.start_line] = task_annotated_calls(child, previous_child, namespace_calls)
+            elsif rake_call?(child, :namespace)
+              annotated_calls_by_task_line(child, [[child, :namespace], *namespace_calls], annotated_calls)
+            else
+              annotated_calls_by_task_line(child, namespace_calls, annotated_calls)
+            end
+          end
+
+          annotated_calls
+        end
+
+        def task_annotated_calls(task_call, previous_child, namespace_calls)
+          desc_calls = rake_call?(previous_child, :desc) ? [[previous_child, :desc]] : []
+
+          [[task_call, :task], *desc_calls, *namespace_calls]
+        end
+
+        def rake_call?(node, method_name)
+          node.is_a?(Prism::CallNode) && node.receiver.nil? && node.name == method_name
+        end
+
+        def magic_comments_above(call, location, comment_lines)
+          line = call.location.start_line - 1
+          magic_comments = []
+
+          while comment_lines.key?(line)
+            match = comment_lines[line].match(MAGIC_COMMENT_REGEX)
+            magic_comments.unshift(Comment.new(name: match[1], raw_value: match[2], location: location)) if match
+            line -= 1
+          end
+
+          magic_comments
+        end
+      end
+    end
+  end
+end