rails-ai-context 5.30.2 → 5.32.0

data/lib/rails_ai_context/introspectors/module_aliases.rb

@@ -76,10 +76,18 @@ module RailsAiContext
       end
 
       # A tsconfig's compilerOptions as its `extends` chain settles them, and
-      # the directory each option was declared in; nil when unreadable.
-      def compiler_options(path, seen = Set.new)
+      # the directory each option was declared in; nil when unreadable. With
+      # `within`, a config is only read through PackageJson.outside_file in that directory.
+      def compiler_options(path, seen = Set.new, within: nil)
         return nil if path.nil? || seen.include?(path) || seen.size > MAX_EXTENDS
 
+        if within
+          full = File.expand_path(path)
+          return nil unless full.start_with?("#{within}/")
+
+          path = RailsAiContext::PackageJson.outside_file(within, full.delete_prefix("#{within}/"))&.to_s or return nil
+        end
+
         seen << path
         text = RailsAiContext::SafeFile.read(path) or return nil
         config = JSON.parse(jsonc(text))
@@ -89,7 +97,7 @@ module RailsAiContext
         dirs = {}
         # A config's own value replaces what it extends; a later `extends` entry replaces an earlier one.
         Array(config["extends"]).each do |spec|
-          parent, parent_dirs = compiler_options(extended_config(spec.to_s, path), seen)
+          parent, parent_dirs = compiler_options(extended_config(spec.to_s, path), seen, within: within)
           options.merge!(parent.to_h)
           dirs.merge!(parent_dirs.to_h)
         end

data/lib/rails_ai_context/introspectors/multi_database_introspector.rb

@@ -1,7 +1,5 @@
 # frozen_string_literal: true
 
-require "yaml"
-
 module RailsAiContext
   module Introspectors
     # Discovers multi-database configuration: multiple databases, replicas,
@@ -10,10 +8,6 @@ module RailsAiContext
       extend StaticTier
       static_tier :files_only
 
-      ERB_SENTINEL = "__rails_ai_context_erb__"
-      # `ENV["X"].presence || "mysql2"`: the literal is what runs with the variable unset.
-      ERB_DEFAULT = /\|\|\s*(["'])([\w.-]+)\1\s*\z/
-
       # @return [Hash] multi-database configuration
       def call
         dbs = discover_databases
@@ -63,7 +57,7 @@ module RailsAiContext
         result[:shard_names] = shard_names if shard_names.any?
 
         # Extract shard config from model source via AST
-        SourceScan.each(root, kind: "app/models").each do |record|
+        model_sources.each do |record|
           ast = SourceIntrospector.walk_source(record.source, {
             connects: -> { Listeners::GenericMacroListener.new(:connects_to) }
           })
@@ -83,16 +77,16 @@ module RailsAiContext
 
       def detect_model_connections
         connections = []
-        SourceScan.classes(root, kind: "app/models").each do |model_name, record|
+        model_classes.each do |model_name, record|
           ast = SourceIntrospector.walk_source(record.source, {
-            connects_to: -> { Listeners::GenericMacroListener.new(:connects_to) },
+            connects_to: -> { Listeners::ConditionalMacroListener.new(:connects_to) },
             connected_to: -> { Listeners::GenericMacroListener.new(:connected_to) }
           })
 
           if ast[:connects_to].any?
             hit = ast[:connects_to].first
             connects_to_text = hit[:options].map { |k, v| "#{k}: #{format_connects_value(v)}" }.join(", ")
-            connections << { model: model_name, connects_to: connects_to_text }
+            connections << { model: model_name, connects_to: connects_to_text, condition: hit[:condition] }.compact
           end
 
           if ast[:connected_to].any?
@@ -130,64 +124,22 @@ module RailsAiContext
         end
       end
 
-      # Read as YAML so anchors, merge keys and comments follow the file format itself.
       def file_databases
-        config = database_yml_env
-        return [] unless config.is_a?(Hash) && config.any?
+        databases = RailsAiContext::DatabaseYml.databases(root)
+        # Rails builds the primary from DATABASE_URL when the file has no entry for the env.
+        return ENV["DATABASE_URL"].to_s.empty? ? [] : [ database_entry("primary", {}) ] if databases.empty?
 
-        # Rails' own rule: an env whose values are all Hashes names one
-        # database per key, anything else is a single primary config.
-        if config.values.all? { |value| value.is_a?(Hash) }
-          config.map { |name, entry| database_entry(name, entry) }
-        else
-          [ database_entry("primary", config) ]
-        end
+        databases.map { |name, entry| database_entry(name, entry) }
       end
 
       def database_entry(name, entry)
-        adapter, from_default = adapter_value(entry["adapter"])
+        adapter, from_default = RailsAiContext::DatabaseYml.adapter(name, entry)
         info = { name: name.to_s, adapter: adapter }
         info[:adapter_default] = true if from_default
         info[:replica] = true if entry["replica"] == true
         info
       end
 
-      # An ERB-computed value is unknown, unless the whole value is one tag carrying its own
-      # literal default, which the sentinel keeps; two tags compose into something neither said.
-      def adapter_value(value)
-        return [ nil, false ] if value.nil?
-
-        text = value.to_s
-        return [ text, false ] unless text.include?(ERB_SENTINEL)
-        return [ nil, false ] unless text.start_with?(ERB_SENTINEL) && text.scan(ERB_SENTINEL).size == 1
-
-        literal = text.delete_prefix(ERB_SENTINEL)
-        literal.empty? ? [ nil, false ] : [ literal, true ]
-      end
-
-      def database_yml_env
-        path = File.join(root, "config/database.yml")
-        return nil unless File.exist?(path)
-
-        content = RailsAiContext::SafeFile.read(path)
-        return nil unless content
-
-        data = YAML.safe_load(neutralize_erb(content), aliases: true, permitted_classes: [ Symbol ])
-        return nil unless data.is_a?(Hash)
-
-        data[RailsAiContext.environment_name]
-      rescue => e
-        RailsAiContext.debug_fail(e, nil, label: "database_yml")
-      end
-
-      # ERB never runs: an output tag becomes an unknown marker, other tags go, and both keep
-      # their newlines so the rest of the file parses at its written indentation.
-      def neutralize_erb(content)
-        content.gsub(RailsAiContext::ErbSource::TAG) do |tag|
-          (tag.start_with?("<%=") ? ERB_SENTINEL + Regexp.last_match(1).to_s[ERB_DEFAULT, 2].to_s : "") + ("\n" * tag.count("\n"))
-        end
-      end
-
       def anonymize_db_name(name)
         return name unless name
 

data/lib/rails_ai_context/introspectors/observability_introspector.rb

@@ -124,16 +124,13 @@ module RailsAiContext
         RailsAiContext.debug_fail(e, {}, label: "detect_server_timing")
       end
 
-      # Rails 8.1 adds `Rails.application.event_reporter`. Report whether it's
-      # available and the subscriber count. We deliberately do NOT call
-      # `reporter.tagged` - it's a block-scoped DSL (`reporter.tagged(:x) { … }`)
-      # that delegates to `TagStack#with_tags` and `yield`s unconditionally, so
-      # a blockless call raises `LocalJumpError`. There is no keyspace to
-      # introspect.
+      # Rails 8.1's reporter is `Rails.event`; the application object has none.
+      # Never call `reporter.tagged`: it yields unconditionally, so a blockless
+      # call raises LocalJumpError.
       def detect_event_reporter
-        return { available: false } unless app.respond_to?(:event_reporter) && app.event_reporter
+        reporter = Rails.event if Rails.respond_to?(:event)
+        return { available: false } unless reporter
 
-        reporter = app.event_reporter
         entry = { available: true }
         entry[:subscriber_count] = reporter.subscribers.size if reporter.respond_to?(:subscribers) && reporter.subscribers.respond_to?(:size)
         entry

data/lib/rails_ai_context/introspectors/performance_introspector.rb

@@ -75,13 +75,14 @@ module RailsAiContext
       end
 
       def load_model_data
-        SourceScan.each(root, kind: "app/models").filter_map do |record|
+        model_sources.filter_map do |record|
           ast = SourceIntrospector.walk_source(record.source, {
             classes: Listeners::ClassDefinitionListener,
             associations: Listeners::AssociationsListener,
             includes: -> { Listeners::ChainedCallListener.new(:includes) },
             tree: TREE_LISTENER,
-            mixins: Listeners::MixinsListener
+            mixins: Listeners::MixinsListener,
+            counter_culture: -> { Listeners::GenericMacroListener.new(:counter_culture) }
           })
 
           # The listener names the class node alone, so the qualified name is
@@ -111,6 +112,7 @@ module RailsAiContext
             has_many: has_many,
             belongs_to: belongs_to,
             tree_parent_keys: tree_parent_keys(ast, class_name),
+            counter_cultures: ast[:counter_culture].map { |c| counter_culture_record(c) },
             includes_calls: includes_calls
           }
         rescue => e
@@ -128,9 +130,9 @@ module RailsAiContext
       # The parent key a tree macro declares, in the model or its concerns.
       # The models section cannot carry it statically: the macro is a gem's.
       def tree_parent_keys(ast, class_name)
-        collected, = ConcernMacros.collect(root, ast[:mixins], keys: %i[tree], prefer: "model",
-                                           within: class_name, cache: (@concern_cache ||= {}),
-                                           listeners: TREE_CONCERN_LISTENERS)
+        collected = ConcernMacros.collect(root, ast[:mixins], keys: %i[tree], prefer: "model",
+                                          within: class_name, cache: (@concern_cache ||= {}),
+                                          listeners: TREE_CONCERN_LISTENERS).collected
         (ast[:tree] + Array(collected[:tree])).map do |macro|
           ((macro[:options] || {})[TREE_MACROS[macro[:macro]]] || "parent_id").to_s
         end
@@ -322,7 +324,6 @@ module RailsAiContext
 
       def detect_missing_counter_cache(model_data, schema_data)
         missing = []
-        written = app_written_counter_columns
 
         model_data.each do |model|
           model[:has_many].each do |assoc|
@@ -338,13 +339,13 @@ module RailsAiContext
             next unless table
             next unless table[:columns].any? { |c| c[:name] == count_col }
             next if options.key?(:counter_cache)
-            next if written.include?(count_col)
+            next if app_written_counter_columns.include?(count_col)
 
             belongs_to_model = association_model(model_data, assoc, model[:name])
             next unless belongs_to_model
             next if belongs_to_model[:belongs_to].any? { |b| b[:options].key?(:counter_cache) }
-
             inverse_name = options[:as] || model[:name].demodulize.underscore
+            next if counter_culture_keeps?(belongs_to_model, inverse_name, count_col)
 
             missing << {
               model: model[:name],
@@ -359,6 +360,25 @@ module RailsAiContext
         missing
       end
 
+      # counter_culture names its column `<child table>_count` unless column_name says
+      # otherwise; a column_name it computes may be this column, so it is not flagged.
+      def counter_culture_keeps?(child, relation, column)
+        Array(child[:counter_cultures]).any? do |culture|
+          next false unless culture[:relation] == relation.to_s
+
+          named = culture.fetch(:column) { "#{child[:name].demodulize.tableize}_count" }
+          named == :computed || named == column
+        end
+      end
+
+      # A multi-level `counter_culture [:a, :b]` counts on a further model and has no relation here.
+      def counter_culture_record(call)
+        node = call[:option_nodes][:column_name]
+        record = { relation: call[:args].first&.to_s }
+        record[:column] = node.is_a?(Prism::StringNode) || node.is_a?(Prism::SymbolNode) ? node.unescaped : :computed if node
+        record
+      end
+
       # The class an association declares is the one the app has;
       # `has_many :remarks, class_name: "Comment"` is answered by Comment, and
       # never by the Remark the name implies. When no model in the app answers

data/lib/rails_ai_context/introspectors/rake_task_introspector.rb

@@ -2,79 +2,146 @@
 
 module RailsAiContext
   module Introspectors
-    # Discovers custom rake tasks from lib/tasks/.
+    # Discovers the app's own commands: rake tasks from the Rakefile, lib/tasks/
+    # and rakelib/, and the generators, generator template overrides and
+    # Railties it keeps under lib/.
     class RakeTaskIntrospector < Base
       extend StaticTier
       static_tier :files_only
 
+      # The names Rake looks for, Rakefile first so a case-insensitive disk prints it as written.
+      RAKEFILES = %w[Rakefile rakefile Rakefile.rb rakefile.rb].freeze
+
       def call
-        tasks_dir = File.join(root, "lib/tasks")
-        return { tasks: [] } unless Dir.exist?(tasks_dir)
+        rakefile = RAKEFILES.map { |name| File.join(root, name) }.find { |path| File.file?(path) }
+        sources = [ rakefile ].compact
+        sources += Dir.glob(File.join(root, "lib/tasks", "**/*.rake")).sort
+        # Rake imports rakelib/*.rake, one level only.
+        sources += Dir.glob(File.join(root, "rakelib", "*.rake")).sort
+
+        {
+          tasks: merge_by_name(sources.flat_map { |path| parse_rake_file(path) }),
+          generators: lib_classes[:generators].sort_by { |g| g[:command] }.presence,
+          generator_templates: generator_templates.presence,
+          railties: lib_classes[:railties].presence
+        }.compact
+      end
+
+      private
+
+      RAILTIE_BASES = %w[Rails::Railtie].freeze
 
-        tasks = Dir.glob(File.join(tasks_dir, "**/*.rake")).sort.flat_map do |path|
-          parse_rake_file(path, tasks_dir)
+      # One pass over lib/ (the cached SourceScan list) for both kinds of class.
+      def lib_classes
+        @lib_classes ||= { generators: [], railties: [] }.tap do |found|
+          SourceScan.each(root, kind: "lib") do |record|
+            if record.file.start_with?("lib/generators/") && record.file.end_with?("_generator.rb")
+              generator = generator_entry(record)
+              found[:generators] << generator if generator
+            elsif record.source.include?("Railtie")
+              found[:railties].concat(railties_in(record))
+            end
+          end
         end
+      end
 
-        { tasks: tasks }
+      # The command Rails::Generators::Base.namespace gives the class:
+      # Admin::PageGenerator answers to `admin:page`.
+      def generator_entry(record)
+        declared = DeclaredConstant.declarations(record.source, path_name: record.path_name).map(&:name).find { |name| name.end_with?("Generator") } or return nil
+        entry = { command: "bin/rails generate #{declared.delete_suffix('Generator').underscore.tr('/', ':')}", file: record.file }
+        usage = SafeFile.read(File.join(File.dirname(record.path), "USAGE"))
+        line = usage&.lines&.map(&:strip)&.find { |text| !text.empty? && text != "Description:" }
+        line ? entry.merge(usage: line) : entry
       end
 
-      private
+      def railties_in(record)
+        railties = DeclaredConstant.declarations(record.source, path_name: record.path_name).select { |d| RAILTIE_BASES.include?(d.superclass.to_s.delete_prefix("::")) }
+        return [] if railties.empty?
+
+        calls = SourceIntrospector.walk_source(record.source, { calls: -> { Listeners::GenericMacroListener.new(:initializer, :rake_tasks) } })[:calls]
+        initializers = calls.select { |c| c[:macro] == :initializer }.filter_map { |c| c[:values].first if c[:values].first.is_a?(String) }
+        railties.map do |railtie|
+          { name: railtie.name, file: record.file, initializers: initializers, rake_tasks: calls.any? { |c| c[:macro] == :rake_tasks } }
+        end
+      end
 
-      def parse_rake_file(path, base_dir)
-        content = RailsAiContext::SafeFile.read(path)
-        return [ { file: path.sub("#{base_dir}/", ""), error: "unreadable" } ] unless content
-        relative = path.sub("#{base_dir}/", "")
+      # Rails adds lib/templates to every generator's source paths ahead of its
+      # own, so a file at lib/templates/<namespace>/ replaces that generator's template.
+      def generator_templates
+        dir = File.join(root, "lib", "templates")
+        return [] unless File.directory?(dir) && SafePath.contained?(File.realpath(dir), File.realpath(root))
 
-        ast_data = SourceIntrospector.walk(path, { rake: -> { Listeners::RakeTaskDslListener.new } })
-        results = ast_data[:rake]
+        Dir.glob(File.join(dir, "**", "*")).sort.filter_map do |path|
+          next unless File.file?(path) && SafePath.contained?(File.realpath(path), File.realpath(root))
 
-        # Track namespace and desc ordering to associate descs with tasks
-        last_desc = nil
-        current_namespace = []
-        namespace_indents = []
-        tasks = []
+          relative = path.delete_prefix("#{dir}/")
+          namespace = File.dirname(relative)
+          next if namespace == "."
 
-        # RakeTaskDslListener returns tasks, descs and namespaces in source
-        # order but without block scope, so where a `namespace` block closes is
-        # tracked by indentation. Regex over the line, not over Ruby structure.
-        line_events = {}
-        results.each { |r| (line_events[r[:location]] ||= []) << r }
+          { file: "lib/templates/#{relative}", generator: namespace.tr("/", ":") }
+        end
+      end
 
-        content.each_line.with_index(1) do |line, line_no|
-          indent = line.match(/^(\s*)/)[1].length
+      # Rake keeps one task per name: a later definition adds its prerequisites and
+      # description, and replaces the arguments only when it names some.
+      def merge_by_name(entries)
+        merged = {}
+        entries.each do |entry|
+          next merged[entry.object_id] = entry if entry[:error]
 
-          if line.match?(/^\s*end\b/) && namespace_indents.any? && indent <= namespace_indents.last
-            current_namespace.pop
-            namespace_indents.pop
-          end
+          task = merged[entry[:name]] ||= { name: entry[:name], comments: [], file: entry[:file] }
+          comment = entry[:description]&.strip
+          task[:comments] << comment if comment.present? && !task[:comments].include?(comment)
+          task[:dependencies] = Array(task[:dependencies]) | entry[:dependencies] if entry[:dependencies]
+          task[:args] = entry[:args] if entry[:args]
+        end
+        merged.values.map do |task|
+          next task if task[:error]
 
-          next unless line_events[line_no]
-
-          line_events[line_no].each do |entry|
-            case entry[:type]
-            when :namespace
-              current_namespace.push(entry[:name])
-              namespace_indents.push(indent)
-            when :desc
-              last_desc = entry[:description]
-            when :task
-              name = (current_namespace + [ entry[:name] ]).join(":")
-              task = {
-                name: name,
-                description: last_desc,
-                file: relative
-              }
-              task[:dependencies] = entry[:deps] if entry[:deps]&.any?
-              task[:args] = entry[:args] if entry[:args]&.any?
-              tasks << task.compact
-              last_desc = nil
-            end
+          comments = task.delete(:comments)
+          task.merge(description: comments.filter_map { |c| first_sentence(c) }.join(" / ").presence).compact
+        end
+      end
+
+      # Rake::Task#first_sentence, which rake -T prints.
+      def first_sentence(text)
+        text.split(/(?<=\w)(\.|!)[ \t]|(\.$|!)|\n/).first
+      end
+
+      def parse_rake_file(path)
+        relative = path.delete_prefix("#{root}/")
+        content, located = RailsAiContext::SafePath.read(relative, under: root)
+        return [] if %i[outside sensitive traversal].include?(located.refusal)
+        return [ { file: relative, error: "unreadable" } ] unless content
+
+        ast_data = SourceIntrospector.walk_source(content, { rake: -> { Listeners::RakeTaskDslListener.new } })
+        results = ast_data[:rake]
+
+        # Rake's desc applies to the next task defined, whatever namespace it is in.
+        last_desc = nil
+        scopes = []
+        tasks = []
+        results.each do |entry|
+          scopes.pop while scopes.any? && entry[:offset] >= scopes.last[:end_offset]
+
+          case entry[:type]
+          when :namespace
+            scopes.push(entry)
+          when :desc
+            last_desc = entry[:description]
+          when :task
+            task = { name: (scopes.map { |ns| ns[:name] } + [ entry[:name] ]).join(":"), description: last_desc, file: relative }
+            task[:dependencies] = entry[:deps] if entry[:deps]&.any?
+            task[:args] = entry[:args] if entry[:args]&.any?
+            tasks << task.compact
+            last_desc = nil
           end
         end
 
         tasks
       rescue => e
-        [ { file: path.sub("#{base_dir}/", ""), error: e.message } ]
+        [ { file: relative, error: e.message } ]
       end
     end
   end

data/lib/rails_ai_context/introspectors/recurring_schedules.rb

@@ -0,0 +1,150 @@
+# frozen_string_literal: true
+
+module RailsAiContext
+  module Introspectors
+    # Recurring tasks from each scheduler's own file, read the way that gem reads it.
+    module RecurringSchedules
+      module_function
+
+      # `assignments` returns a config file's ConfigAssignmentListener hits from the caller's own walk, [] when it never names good_job.
+      def read(root, assignments)
+        solid_queue(root) + sidekiq_cron(root) + sidekiq_scheduler(root) + good_job(root, assignments) + whenever(root)
+      end
+
+      # Solid Queue takes the section named for the environment, else the whole file,
+      # and keeps only the entries that carry a `schedule`.
+      def solid_queue(root)
+        file = "config/recurring.yml"
+        data = yaml(root, file)
+        return [] unless data.is_a?(Hash)
+
+        data.flat_map do |key, value|
+          next [] unless value.is_a?(Hash)
+          next [ task(file, key, value, :schedule) ].compact if value.key?("schedule")
+
+          value.filter_map { |name, options| task(file, name, options, :schedule, env: key) }
+        end
+      end
+
+      def sidekiq_cron(root)
+        %w[config/schedule.yml config/schedule.yaml config/sidekiq_cron.yml].flat_map do |file|
+          named_tasks(yaml(root, file)).filter_map { |name, options| task(file, name, options, :cron) }
+        end
+      end
+
+      # sidekiq-scheduler runs a job by its entry's name when no class is given.
+      def sidekiq_scheduler(root)
+        file = "config/sidekiq.yml"
+        data = yaml(root, file)
+        return [] unless data.is_a?(Hash)
+
+        section = data["scheduler"].is_a?(Hash) ? data["scheduler"]["schedule"] : data["schedule"]
+        named_tasks(section).filter_map do |name, options|
+          next unless options.is_a?(Hash)
+
+          kind = SCHEDULER_KEYS.find { |key| options.key?(key.to_s) } or next
+          task(file, name, { "class" => name }.merge(options), kind)
+        end
+      end
+
+      SCHEDULER_KEYS = %i[cron every at in interval].freeze
+
+      # In the order Rails loads them; initializers at any depth, sorted by path.
+      GOOD_JOB_FILES = %w[config/application.rb config/environments/*.rb config/initializers/**/*.rb].freeze
+
+      # `config.good_job.cron = {...}`, or entries merged into it (apps also merge! in after_initialize).
+      GOOD_JOB_CRON = [ %i[good_job cron], %i[good_job cron merge!], %i[good_job cron update] ].freeze
+
+      # `cron =` replaces the hash, dropping what earlier files set; an environment
+      # file's assignment drops only that file's earlier entries.
+      def good_job(root, assignments)
+        GOOD_JOB_FILES.flat_map { |pattern| Dir.glob(pattern, base: root.to_s).sort }.each_with_object([]) do |file, tasks|
+          env = File.basename(file, ".rb") if file.start_with?("config/environments/")
+          assignments.call(file).each do |hit|
+            next unless GOOD_JOB_CRON.include?(hit[:path])
+
+            tasks.reject! { |entry| env.nil? || entry[:file] == file } if hit[:assignment] && !hit[:condition]
+            next unless hit[:value].is_a?(Hash)
+
+            tasks.concat(hit[:value].filter_map { |name, options| task(file, name, stringify(options), :cron, env: env) })
+          end
+        end
+      end
+
+      WHENEVER_JOBS = %i[runner rake command].freeze
+
+      # `every 1.day, at: "4:30 am" do runner "CleanupJob.perform_later" end`: the job is
+      # the constant the runner's code starts with.
+      def whenever(root)
+        file = "config/schedule.rb"
+        source = read_file(root, file) or return []
+        hits = SourceIntrospector.walk_source(source, {
+          every: -> { Listeners::GenericMacroListener.new(:every, *WHENEVER_JOBS) }
+        })[:every]
+        everies = hits.select { |hit| hit[:macro] == :every }.to_h { |hit| [ hit[:offset], hit ] }
+        hits.filter_map do |hit|
+          every = everies[hit[:parent_offset]]
+          code = hit[:values].first
+          next unless every && WHENEVER_JOBS.include?(hit[:macro]) && code.is_a?(String)
+
+          klass = code[/\A\s*(?:::)?([A-Z]\w*(?:::[A-Z]\w*)*)\./, 1] if hit[:macro] == :runner
+          { class: klass, command: hit[:macro] == :runner ? code : "#{hit[:macro]} #{code}",
+            schedule: whenever_schedule(every), file: file }.compact
+        end
+      end
+
+      def whenever_schedule(every)
+        text = "every #{every[:values].first}"
+        at = every[:option_values][:at]
+        at ? "#{text} at #{at}" : text
+      end
+
+      def task(file, name, options, kind, env: nil)
+        return nil unless options.is_a?(Hash)
+
+        options = options.transform_values { |value| computed?(value) ? :computed : value }
+        schedule = options[kind.to_s]
+        return nil if schedule.nil?
+
+        # sidekiq-scheduler's `every: ['5m', first_in: '4m']`: the interval, then its options.
+        schedule = Array(schedule).flat_map { |part| part.is_a?(Hash) ? part.map { |key, value| "#{key}: #{value}" } : [ part ] }.join(", ")
+
+        klass = options["class"] || options["klass"]
+        computed = ("class" if klass == :computed) || ("command" if options["command"] == :computed)
+        klass = nil if klass == :computed
+        command = options["command"] unless options["command"] == :computed
+        { name: computed?(name.to_s) ? "computed" : name.to_s, class: klass&.to_s&.delete_prefix("::"), command: command&.to_s,
+          computed: computed, schedule: schedule.to_s, env: computed?(env.to_s) ? "computed" : env&.to_s, file: file }.compact
+      end
+
+      ERB_OUTPUT = ConfigYaml::ERB_OUTPUT
+
+      def computed?(value)
+        value == RailsAiContext::Confidence::INFERRED || ConfigYaml.marked?(value) ||
+          (value.is_a?(Array) && value.any? { |part| computed?(part) }) ||
+          (value.is_a?(Hash) && value.values.any? { |part| computed?(part) })
+      end
+
+      # sidekiq-cron accepts a hash keyed by name or a list of hashes that carry it.
+      def named_tasks(data)
+        case data
+        when Hash then data.to_a
+        when Array then data.filter_map { |entry| [ entry["name"], entry ] if entry.is_a?(Hash) }
+        else []
+        end
+      end
+
+      def stringify(value)
+        value.is_a?(Hash) ? value.to_h { |key, inner| [ key.to_s, inner ] } : value
+      end
+
+      def yaml(root, file)
+        ConfigYaml.read(root, file, label: "schedule", marker: ERB_OUTPUT)
+      end
+
+      def read_file(root, file)
+        SafePath.read(file, under: root.to_s).first
+      end
+    end
+  end
+end