codebase_index 0.1.0

data/lib/codebase_index/extractors/scheduled_job_extractor.rb

@@ -0,0 +1,331 @@
+# frozen_string_literal: true
+
+require 'yaml'
+
+module CodebaseIndex
+  module Extractors
+    # ScheduledJobExtractor handles scheduled/recurring job configuration extraction.
+    #
+    # Scans three schedule file formats to extract one unit per scheduled entry:
+    # - `config/recurring.yml` — Solid Queue recurring tasks
+    # - `config/sidekiq_cron.yml` — Sidekiq-Cron scheduled jobs
+    # - `config/schedule.rb` — Whenever DSL
+    #
+    # Each scheduled entry becomes its own ExtractedUnit with type `:scheduled_job`.
+    # Identifiers are prefixed with "scheduled:" to avoid collision with JobExtractor units.
+    #
+    # @example
+    #   extractor = ScheduledJobExtractor.new
+    #   units = extractor.extract_all
+    #   cleanup = units.find { |u| u.identifier == "scheduled:periodic_cleanup" }
+    #
+    class ScheduledJobExtractor
+      # Schedule files to scan, mapped to their format
+      SCHEDULE_FILES = {
+        'config/recurring.yml' => :solid_queue,
+        'config/sidekiq_cron.yml' => :sidekiq_cron,
+        'config/schedule.rb' => :whenever
+      }.freeze
+
+      # Common cron patterns mapped to human-readable descriptions
+      CRON_HUMANIZE = {
+        '* * * * *' => 'every minute',
+        '0 * * * *' => 'every hour',
+        '0 0 * * *' => 'daily at midnight',
+        '0 0 * * 0' => 'weekly on Sunday',
+        '0 0 * * 1' => 'weekly on Monday',
+        '0 0 1 * *' => 'monthly on the 1st',
+        '0 0 1 1 *' => 'yearly on January 1st'
+      }.freeze
+
+      # Environment keys to unwrap when nested in YAML
+      ENVIRONMENT_KEYS = %w[production development test staging].freeze
+
+      def initialize
+        @schedule_files = SCHEDULE_FILES.each_with_object({}) do |(relative_path, format), hash|
+          full_path = Rails.root.join(relative_path)
+          hash[full_path.to_s] = format if File.exist?(full_path)
+        end
+      end
+
+      # Extract all scheduled job entries from all discovered schedule files.
+      #
+      # @return [Array<ExtractedUnit>] List of scheduled job units
+      def extract_all
+        @schedule_files.flat_map do |file_path, format|
+          extract_scheduled_job_file(file_path, format)
+        end
+      end
+
+      # Extract scheduled job entries from a single schedule file.
+      #
+      # Unlike other file-based extractors that return a single ExtractedUnit,
+      # this returns an Array because each schedule file contains multiple entries.
+      #
+      # @param file_path [String] Path to the schedule file
+      # @param format [Symbol, nil] One of :solid_queue, :sidekiq_cron, :whenever (inferred from filename if nil)
+      # @return [Array<ExtractedUnit>] List of scheduled job units
+      def extract_scheduled_job_file(file_path, format = nil)
+        format ||= infer_format(file_path)
+        case format
+        when :solid_queue, :sidekiq_cron
+          extract_yaml_schedule(file_path, format)
+        when :whenever
+          extract_whenever_schedule(file_path)
+        else
+          []
+        end
+      rescue StandardError => e
+        Rails.logger.error("Failed to extract scheduled jobs from #{file_path}: #{e.message}")
+        []
+      end
+
+      private
+
+      # ──────────────────────────────────────────────────────────────────────
+      # YAML-based formats (Solid Queue, Sidekiq-Cron)
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Parse a YAML schedule file and produce units.
+      #
+      # @param file_path [String] Path to the YAML file
+      # @param format [Symbol] :solid_queue or :sidekiq_cron
+      # @return [Array<ExtractedUnit>]
+      def extract_yaml_schedule(file_path, format)
+        source = File.read(file_path)
+        data = YAML.safe_load(source, permitted_classes: [Symbol])
+
+        return [] unless data.is_a?(Hash) && data.any?
+
+        entries = unwrap_environment_nesting(data)
+        return [] unless entries.is_a?(Hash)
+
+        entries.filter_map do |task_name, config|
+          next unless config.is_a?(Hash)
+
+          build_yaml_unit(task_name, config, file_path, source, format)
+        end
+      end
+
+      # Detect and unwrap environment-nested YAML.
+      #
+      # If the top-level keys are environment names (production, development, etc.),
+      # unwrap to the first environment's entries.
+      #
+      # @param data [Hash] Parsed YAML data
+      # @return [Hash] Unwrapped entries
+      def unwrap_environment_nesting(data)
+        if data.keys.all? { |k| ENVIRONMENT_KEYS.include?(k.to_s) }
+          data.values.first || {}
+        else
+          data
+        end
+      end
+
+      # Build an ExtractedUnit from a YAML schedule entry.
+      #
+      # @param task_name [String] The task/job name key
+      # @param config [Hash] The entry configuration
+      # @param file_path [String] Path to the schedule file
+      # @param source [String] Raw file content
+      # @param format [Symbol] :solid_queue or :sidekiq_cron
+      # @return [ExtractedUnit]
+      def build_yaml_unit(task_name, config, file_path, source, format)
+        job_class = config['class']
+        cron = extract_cron(config, format)
+
+        unit = ExtractedUnit.new(
+          type: :scheduled_job,
+          identifier: "scheduled:#{task_name}",
+          file_path: file_path
+        )
+
+        unit.namespace = job_class.include?('::') ? job_class.split('::')[0..-2].join('::') : nil if job_class
+        unit.source_code = source
+        unit.metadata = {
+          schedule_format: format,
+          job_class: job_class,
+          cron_expression: cron,
+          queue: config['queue'],
+          args: config['args'],
+          frequency_human_readable: humanize_frequency(cron, format)
+        }
+        unit.dependencies = build_dependencies(job_class)
+
+        unit
+      end
+
+      # Extract the cron/schedule expression from config.
+      #
+      # @param config [Hash] Entry configuration
+      # @param format [Symbol] :solid_queue or :sidekiq_cron
+      # @return [String, nil]
+      def extract_cron(config, format)
+        case format
+        when :solid_queue
+          config['schedule']
+        when :sidekiq_cron
+          config['cron']
+        end
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Whenever DSL (config/schedule.rb)
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Parse a Whenever schedule.rb file using regex.
+      #
+      # @param file_path [String] Path to the schedule.rb file
+      # @return [Array<ExtractedUnit>]
+      def extract_whenever_schedule(file_path)
+        source = File.read(file_path)
+        blocks = parse_whenever_blocks(source)
+
+        blocks.each_with_index.map do |block, index|
+          build_whenever_unit(block, index, file_path, source)
+        end
+      end
+
+      # Parse `every ... do ... end` blocks from Whenever DSL.
+      #
+      # @param source [String] Ruby source code
+      # @return [Array<Hash>] Parsed block data
+      def parse_whenever_blocks(source)
+        blocks = []
+        # Match: every <frequency>[, options] do ... end
+        source.scan(/every\s+(.+?)\s+do\s*\n(.*?)end/m) do |frequency_str, body|
+          # Clean up the frequency — strip trailing options like ", at: '...'"
+          frequency = frequency_str.strip.sub(/,\s*at:.*\z/, '').strip
+
+          command_type, command_body = detect_whenever_command(body)
+          job_class = extract_job_class_from_runner(command_body) if command_type == :runner
+
+          blocks << {
+            frequency: frequency,
+            frequency_str: frequency_str.strip,
+            command_type: command_type,
+            command_body: command_body,
+            job_class: job_class
+          }
+        end
+
+        blocks
+      end
+
+      # Detect the command type inside a Whenever block body.
+      #
+      # @param body [String] Block body content
+      # @return [Array<Symbol, String>] Command type and body
+      def detect_whenever_command(body)
+        case body
+        when /runner\s+"([^"]+)"/
+          [:runner, ::Regexp.last_match(1)]
+        when /rake\s+"([^"]+)"/
+          [:rake, ::Regexp.last_match(1)]
+        when /command\s+"([^"]+)"/
+          [:command, ::Regexp.last_match(1)]
+        else
+          [:unknown, body.strip]
+        end
+      end
+
+      # Extract a job class name from a runner string.
+      #
+      # Looks for patterns like `MyJob.perform_later` or `MyJob.perform_now`.
+      #
+      # @param runner_str [String] The runner command string
+      # @return [String, nil] The job class name or nil
+      def extract_job_class_from_runner(runner_str)
+        return nil unless runner_str
+
+        match = runner_str.match(/([A-Z]\w*(?:::\w+)*)\.perform_(later|now)/)
+        match ? match[1] : nil
+      end
+
+      # Build an ExtractedUnit from a Whenever block.
+      #
+      # @param block [Hash] Parsed block data
+      # @param index [Integer] Block index for identifier uniqueness
+      # @param file_path [String] Path to schedule.rb
+      # @param source [String] Raw file content
+      # @return [ExtractedUnit]
+      def build_whenever_unit(block, index, file_path, source)
+        identifier = if block[:job_class]
+                       "scheduled:whenever_#{block[:job_class].underscore}_#{index}"
+                     else
+                       "scheduled:whenever_task_#{index}"
+                     end
+
+        unit = ExtractedUnit.new(
+          type: :scheduled_job,
+          identifier: identifier,
+          file_path: file_path
+        )
+
+        unit.namespace = block[:job_class].split('::')[0..-2].join('::') if block[:job_class]&.include?('::')
+        unit.source_code = source
+        unit.metadata = {
+          schedule_format: :whenever,
+          job_class: block[:job_class],
+          cron_expression: block[:frequency],
+          command_type: block[:command_type],
+          frequency_human_readable: block[:frequency]
+        }
+        unit.dependencies = build_dependencies(block[:job_class])
+
+        unit
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Format Detection
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Infer the schedule format from the file path.
+      #
+      # @param file_path [String] Path to the schedule file
+      # @return [Symbol] One of :solid_queue, :sidekiq_cron, :whenever
+      def infer_format(file_path)
+        basename = File.basename(file_path)
+        SCHEDULE_FILES.each do |relative, fmt|
+          return fmt if basename == File.basename(relative)
+        end
+        :unknown
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Shared helpers
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Build dependency array linking to a job class.
+      #
+      # @param job_class [String, nil] The job class name
+      # @return [Array<Hash>]
+      def build_dependencies(job_class)
+        return [] unless job_class
+
+        [{ type: :job, target: job_class, via: :scheduled }]
+      end
+
+      # Humanize a cron expression or Solid Queue frequency string.
+      #
+      # @param expression [String, nil] Cron expression or frequency
+      # @param format [Symbol] Schedule format
+      # @return [String, nil]
+      def humanize_frequency(expression, format)
+        return nil unless expression
+
+        # Solid Queue schedules are already human-readable
+        return expression if format == :solid_queue
+
+        # Check exact matches
+        return CRON_HUMANIZE[expression] if CRON_HUMANIZE.key?(expression)
+
+        # Check */N minute pattern
+        return "every #{::Regexp.last_match(1)} minutes" if expression =~ %r{\A\*/(\d+) \* \* \* \*\z}
+
+        # Fallback: return raw expression
+        expression
+      end
+    end
+  end
+end

data/lib/codebase_index/extractors/serializer_extractor.rb

@@ -0,0 +1,334 @@
+# frozen_string_literal: true
+
+require_relative 'shared_utility_methods'
+require_relative 'shared_dependency_scanner'
+
+module CodebaseIndex
+  module Extractors
+    # SerializerExtractor handles extraction of serializers, blueprinters, and decorators.
+    #
+    # Serializers define the API contract — what data is exposed and how it's shaped.
+    # They often wrap models, select attributes, and define associations that map
+    # directly to JSON responses. Understanding these is critical for API-aware
+    # code analysis.
+    #
+    # Supports:
+    # - ActiveModel::Serializer (AMS)
+    # - Blueprinter::Base
+    # - Draper::Decorator
+    #
+    # @example
+    #   extractor = SerializerExtractor.new
+    #   units = extractor.extract_all
+    #   user_serializer = units.find { |u| u.identifier == "UserSerializer" }
+    #
+    class SerializerExtractor
+      include SharedUtilityMethods
+      include SharedDependencyScanner
+
+      # Directories to scan for serializer-like files
+      SERIALIZER_DIRECTORIES = %w[
+        app/serializers
+        app/blueprinters
+        app/decorators
+      ].freeze
+
+      # Known base classes for runtime discovery
+      BASE_CLASSES = {
+        'ActiveModel::Serializer' => :ams,
+        'Blueprinter::Base' => :blueprinter,
+        'Draper::Decorator' => :draper
+      }.freeze
+
+      def initialize
+        @directories = SERIALIZER_DIRECTORIES.map { |d| Rails.root.join(d) }
+                                             .select(&:directory?)
+      end
+
+      # Extract all serializers, blueprinters, and decorators in the application
+      #
+      # @return [Array<ExtractedUnit>] List of serializer units
+      def extract_all
+        units = []
+
+        # File-based discovery (catches everything in known directories)
+        @directories.each do |dir|
+          Dir[dir.join('**/*.rb')].each do |file|
+            unit = extract_serializer_file(file)
+            units << unit if unit
+          end
+        end
+
+        # Class-based discovery for loaded gems
+        seen = units.to_set(&:identifier)
+        BASE_CLASSES.each_key do |base_class_name|
+          base_class = begin
+            base_class_name.constantize
+          rescue NameError
+            nil
+          end
+          next unless base_class
+
+          base_class.descendants.each do |klass|
+            next if klass.name.nil?
+            next if seen.include?(klass.name)
+
+            unit = extract_serializer_class(klass, base_class_name)
+            if unit
+              units << unit
+              seen << unit.identifier
+            end
+          end
+        end
+
+        units.compact
+      end
+
+      # Extract a serializer from its file
+      #
+      # @param file_path [String] Path to the serializer file
+      # @return [ExtractedUnit, nil] The extracted unit, or nil if not a serializer
+      def extract_serializer_file(file_path)
+        source = File.read(file_path)
+        class_name = extract_class_name(file_path, source)
+
+        return nil unless class_name
+        return nil unless serializer_file?(source)
+
+        unit = ExtractedUnit.new(
+          type: :serializer,
+          identifier: class_name,
+          file_path: file_path
+        )
+
+        unit.namespace = extract_namespace(class_name)
+        unit.source_code = annotate_source(source, class_name)
+        unit.metadata = extract_metadata_from_source(source, class_name)
+        unit.dependencies = extract_dependencies(source)
+
+        unit
+      rescue StandardError => e
+        Rails.logger.error("Failed to extract serializer #{file_path}: #{e.message}")
+        nil
+      end
+
+      private
+
+      # Extract a serializer from its class (runtime introspection)
+      #
+      # @param klass [Class] The serializer class
+      # @param base_class_name [String] Name of the detected base class
+      # @return [ExtractedUnit, nil] The extracted unit
+      def extract_serializer_class(klass, base_class_name)
+        return nil if klass.name.nil?
+
+        file_path = source_file_for(klass)
+        source = file_path && File.exist?(file_path) ? File.read(file_path) : ''
+
+        unit = ExtractedUnit.new(
+          type: :serializer,
+          identifier: klass.name,
+          file_path: file_path
+        )
+
+        unit.namespace = extract_namespace(klass.name)
+        unit.source_code = annotate_source(source, klass.name)
+        unit.metadata = extract_metadata_from_class(klass, source, base_class_name)
+        unit.dependencies = extract_dependencies(source)
+
+        unit
+      rescue StandardError => e
+        Rails.logger.error("Failed to extract serializer #{klass.name}: #{e.message}")
+        nil
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Class Discovery
+      # ──────────────────────────────────────────────────────────────────────
+
+      def extract_class_name(file_path, source)
+        return ::Regexp.last_match(1) if source =~ /^\s*class\s+([\w:]+)/
+
+        # Fall back to convention
+        file_path
+          .sub("#{Rails.root}/", '')
+          .sub(%r{^app/(serializers|blueprinters|decorators)/}, '')
+          .sub('.rb', '')
+          .camelize
+      end
+
+      def serializer_file?(source)
+        source.match?(/< ActiveModel::Serializer/) ||
+          source.match?(/< Blueprinter::Base/) ||
+          source.match?(/< Draper::Decorator/) ||
+          source.match?(/< ApplicationSerializer/) ||
+          source.match?(/< ApplicationDecorator/) ||
+          source.match?(/< BaseSerializer/) ||
+          source.match?(/< BaseBlueprinter/) ||
+          source.match?(/attributes?\s+:/) ||
+          source.match?(/has_many\s+:.*serializer/) ||
+          source.match?(/belongs_to\s+:.*serializer/) ||
+          source.match?(/view\s+:/) # Blueprinter views
+      end
+
+      def source_file_for(klass)
+        methods = klass.instance_methods(false)
+        if methods.any?
+          klass.instance_method(methods.first).source_location&.first
+        end || Rails.root.join("app/serializers/#{klass.name.underscore}.rb").to_s
+      rescue StandardError
+        nil
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Source Annotation
+      # ──────────────────────────────────────────────────────────────────────
+
+      def annotate_source(source, class_name)
+        serializer_type = detect_serializer_type(source)
+        wrapped_model = detect_wrapped_model(source, class_name)
+
+        <<~ANNOTATION
+          # ╔═══════════════════════════════════════════════════════════════════════╗
+          # ║ Serializer: #{class_name.ljust(57)}║
+          # ║ Type: #{serializer_type.to_s.ljust(61)}║
+          # ║ Wraps: #{(wrapped_model || 'unknown').ljust(60)}║
+          # ╚═══════════════════════════════════════════════════════════════════════╝
+
+          #{source}
+        ANNOTATION
+      end
+
+      def detect_serializer_type(source)
+        return :ams if source.match?(/< ActiveModel::Serializer/) || source.match?(/< ApplicationSerializer/)
+        return :blueprinter if source.match?(/< Blueprinter::Base/) || source.match?(/< BaseBlueprinter/)
+        return :draper if source.match?(/< Draper::Decorator/) || source.match?(/< ApplicationDecorator/)
+
+        :unknown
+      end
+
+      def detect_wrapped_model(source, class_name)
+        # AMS: `type` declaration
+        return ::Regexp.last_match(1).classify if source =~ /type\s+[:"'](\w+)/
+
+        # Draper: `decorates` declaration
+        return ::Regexp.last_match(1).classify if source =~ /decorates\s+[:"'](\w+)/
+
+        # Convention: strip Serializer/Decorator/Blueprinter suffix
+        class_name
+          .split('::')
+          .last
+          .sub(/Serializer$/, '')
+          .sub(/Decorator$/, '')
+          .sub(/Blueprinter$/, '')
+          .sub(/Blueprint$/, '')
+          .then { |name| name.empty? ? nil : name }
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Metadata Extraction (from source)
+      # ──────────────────────────────────────────────────────────────────────
+
+      def extract_metadata_from_source(source, class_name)
+        {
+          serializer_type: detect_serializer_type(source),
+          wrapped_model: detect_wrapped_model(source, class_name),
+          attributes: extract_attributes(source),
+          associations: extract_associations(source),
+          custom_methods: extract_custom_methods(source),
+          views: extract_views(source),
+          loc: source.lines.count { |l| l.strip.length.positive? && !l.strip.start_with?('#') }
+        }
+      end
+
+      def extract_metadata_from_class(klass, source, base_class_name)
+        base_metadata = extract_metadata_from_source(source, klass.name)
+        base_metadata[:serializer_type] = BASE_CLASSES[base_class_name] || base_metadata[:serializer_type]
+
+        # Enhance with runtime introspection if available
+        if klass.respond_to?(:_attributes_data)
+          # AMS runtime attributes
+          runtime_attrs = klass._attributes_data.keys.map(&:to_s)
+          base_metadata[:attributes] = runtime_attrs if runtime_attrs.any?
+        elsif klass.respond_to?(:definition)
+          # Blueprinter runtime fields
+          definition = klass.definition
+          base_metadata[:views] = definition.keys.map(&:to_s) if definition.respond_to?(:keys)
+        end
+
+        base_metadata
+      end
+
+      def extract_attributes(source)
+        attrs = []
+
+        # AMS / generic: `attributes :name, :email, :created_at`
+        source.scan(/attributes?\s+((?::\w+(?:,\s*)?)+)/).each do |match|
+          match[0].scan(/:(\w+)/).flatten.each { |a| attrs << a }
+        end
+
+        # Blueprinter: `field :name` or `identifier :id`
+        source.scan(/(?:field|identifier)\s+:(\w+)/).flatten.each { |a| attrs << a }
+
+        # Draper: `delegate :name, :email, to: :object`
+        source.scan(/delegate\s+((?::\w+(?:,\s*)?)+)\s*,\s*to:\s*:object/).each do |match|
+          match[0].scan(/:(\w+)/).flatten.each { |a| attrs << a }
+        end
+
+        attrs.uniq
+      end
+
+      def extract_associations(source)
+        assocs = []
+
+        # AMS: `has_many :comments`, `belongs_to :author`, `has_one :profile`
+        source.scan(/(has_many|has_one|belongs_to)\s+:(\w+)(?:,\s*serializer:\s*([\w:]+))?/) do |type, name, serializer|
+          assocs << { type: type, name: name, serializer: serializer }.compact
+        end
+
+        # Blueprinter: `association :comments, blueprint: CommentBlueprint`
+        source.scan(/association\s+:(\w+)(?:,\s*blueprint:\s*([\w:]+))?/) do |name, blueprint|
+          assocs << { type: 'association', name: name, serializer: blueprint }.compact
+        end
+
+        assocs
+      end
+
+      def extract_custom_methods(source)
+        methods = []
+
+        # Instance methods defined in the class (excluding standard callbacks)
+        source.scan(/def\s+(\w+)/).flatten.each do |method_name|
+          next if %w[initialize].include?(method_name)
+
+          methods << method_name
+        end
+
+        methods
+      end
+
+      def extract_views(source)
+        # Blueprinter views: `view :extended do`
+        source.scan(/view\s+:(\w+)/).flatten.map { |v| v }
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Dependency Extraction
+      # ──────────────────────────────────────────────────────────────────────
+
+      def extract_dependencies(source)
+        deps = []
+        deps.concat(scan_model_dependencies(source, via: :serialization))
+
+        # Other serializers referenced (e.g., `serializer: CommentSerializer`)
+        source.scan(/(?:serializer|blueprint):\s*([\w:]+)/).flatten.uniq.each do |serializer|
+          deps << { type: :serializer, target: serializer, via: :serialization }
+        end
+
+        deps.concat(scan_service_dependencies(source))
+
+        deps.uniq { |d| [d[:type], d[:target]] }
+      end
+    end
+  end
+end