codebase_index 0.1.0

data/lib/codebase_index/extractors/lib_extractor.rb

@@ -0,0 +1,249 @@
+# frozen_string_literal: true
+
+require_relative 'shared_utility_methods'
+require_relative 'shared_dependency_scanner'
+
+module CodebaseIndex
+  module Extractors
+    # LibExtractor handles extraction of Ruby files from lib/.
+    #
+    # The lib/ directory contains application infrastructure that sits outside
+    # Rails' app/ convention: custom middleware, client wrappers, utility classes,
+    # domain-specific libraries, and framework extensions. These are often heavily
+    # referenced but invisible to app/-only extractors.
+    #
+    # Excludes:
+    # - lib/tasks/ — handled by RakeTaskExtractor
+    # - lib/generators/ — Rails generator scaffolding, not application code
+    #
+    # Handles:
+    # - Plain Ruby classes (with or without inheritance)
+    # - Module-only files (standalone modules without a class)
+    # - Namespaced classes (e.g., lib/external/analytics.rb → External::Analytics)
+    # - Files with multiple class definitions
+    #
+    # @example
+    #   extractor = LibExtractor.new
+    #   units = extractor.extract_all
+    #   analytics = units.find { |u| u.identifier == "External::Analytics" }
+    #   analytics.metadata[:entry_points]  # => ["call"]
+    #   analytics.metadata[:parent_class]  # => nil
+    #
+    class LibExtractor
+      include SharedUtilityMethods
+      include SharedDependencyScanner
+
+      # Root directory to scan
+      LIB_DIRECTORY = 'lib'
+
+      # Subdirectories to exclude from extraction
+      EXCLUDED_SEGMENTS = %w[/tasks/ /generators/].freeze
+
+      def initialize
+        @lib_dir = Rails.root.join(LIB_DIRECTORY)
+      end
+
+      # Extract all lib units from lib/**/*.rb (excluding tasks and generators).
+      #
+      # @return [Array<ExtractedUnit>] List of lib units
+      def extract_all
+        return [] unless @lib_dir.directory?
+
+        Dir[@lib_dir.join('**/*.rb')].filter_map do |file|
+          next if excluded_path?(file)
+
+          extract_lib_file(file)
+        end
+      end
+
+      # Extract a single lib file.
+      #
+      # Returns nil if the file cannot be read or yields no extractable unit.
+      # Module-only files are extracted (unlike some other extractors) since
+      # lib/ commonly contains standalone utility modules.
+      #
+      # @param file_path [String] Absolute path to the Ruby file
+      # @return [ExtractedUnit, nil] The extracted unit or nil on failure
+      def extract_lib_file(file_path)
+        source = File.read(file_path)
+
+        class_name = infer_class_name(file_path, source)
+        return nil unless class_name
+
+        unit = ExtractedUnit.new(
+          type: :lib,
+          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(source, class_name)
+        unit.dependencies = extract_dependencies(source)
+
+        unit
+      rescue StandardError => e
+        Rails.logger.error("Failed to extract lib file #{file_path}: #{e.message}")
+        nil
+      end
+
+      private
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Path Filtering
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Return true when the file path falls inside an excluded subdirectory.
+      #
+      # @param file_path [String] Absolute path to the file
+      # @return [Boolean]
+      def excluded_path?(file_path)
+        EXCLUDED_SEGMENTS.any? { |seg| file_path.include?(seg) }
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Class / Module Name Inference
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Infer the primary constant name from source or fall back to file path.
+      #
+      # For files with a class definition, combines outer module namespaces
+      # with the class name. For module-only files, uses the outermost module
+      # name (joined with inner modules). Falls back to path-based camelize
+      # when neither is present.
+      #
+      # @param file_path [String] Absolute path to the file
+      # @param source [String] Ruby source code
+      # @return [String, nil] The inferred constant name, or nil for empty files
+      def infer_class_name(file_path, source)
+        return nil if source.strip.empty?
+
+        # Class definition — combine outer modules + class name
+        class_match = source.match(/^\s*class\s+([\w:]+)/)
+        if class_match
+          base = class_match[1]
+          return base if base.include?('::')
+
+          namespaces = source.scan(/^\s*module\s+([\w:]+)/).flatten
+          return namespaces.any? ? "#{namespaces.join('::')}::#{base}" : base
+        end
+
+        # Module-only file — use the outermost module chain
+        modules = source.scan(/^\s*module\s+([\w:]+)/).flatten
+        return modules.join('::') if modules.any?
+
+        # Fall back to path-based naming
+        path_based_class_name(file_path)
+      end
+
+      # Derive a constant name from a lib/ file path.
+      #
+      # lib/external/analytics.rb      => External::Analytics
+      # lib/json_api/serializer.rb      => JsonApi::Serializer
+      # lib/my_gem.rb                   => MyGem
+      #
+      # @param file_path [String] Absolute path to the file
+      # @return [String] Camelize-derived constant name
+      def path_based_class_name(file_path)
+        relative = file_path.sub("#{Rails.root}/", '')
+        relative
+          .sub(%r{^lib/}, '')
+          .sub('.rb', '')
+          .split('/')
+          .map(&:camelize)
+          .join('::')
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Source Annotation
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Prepend a summary annotation header to the source.
+      #
+      # @param source [String] Ruby source code
+      # @param class_name [String] The inferred constant name
+      # @return [String] Annotated source
+      def annotate_source(source, class_name)
+        parent = extract_parent_class(source)
+        entry_points = detect_entry_points(source)
+        parent_label = parent || 'none'
+
+        annotation = <<~ANNOTATION
+          # ╔═══════════════════════════════════════════════════════════════════════╗
+          # ║ Lib: #{class_name.ljust(65)}║
+          # ║ Parent: #{parent_label.ljust(61)}║
+          # ║ Entry Points: #{entry_points.join(', ').ljust(55)}║
+          # ╚═══════════════════════════════════════════════════════════════════════╝
+
+        ANNOTATION
+
+        annotation + source
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Metadata Extraction
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Build the metadata hash for a lib unit.
+      #
+      # @param source [String] Ruby source code
+      # @param class_name [String] The inferred constant name
+      # @return [Hash] Lib unit metadata
+      def extract_metadata(source, _class_name)
+        {
+          public_methods: extract_public_methods(source),
+          class_methods: extract_class_methods(source),
+          initialize_params: extract_initialize_params(source),
+          parent_class: extract_parent_class(source),
+          loc: count_loc(source),
+          method_count: source.scan(/def\s+(?:self\.)?\w+/).size,
+          entry_points: detect_entry_points(source)
+        }
+      end
+
+      # Extract the parent class name from a class definition.
+      #
+      # @param source [String] Ruby source code
+      # @return [String, nil] Parent class name or nil
+      def extract_parent_class(source)
+        match = source.match(/^\s*class\s+[\w:]+\s*<\s*([\w:]+)/)
+        match ? match[1] : nil
+      end
+
+      # Count non-blank, non-comment lines of code.
+      #
+      # @param source [String] Ruby source code
+      # @return [Integer] LOC count
+      def count_loc(source)
+        source.lines.count { |l| l.strip.length.positive? && !l.strip.start_with?('#') }
+      end
+
+      # Detect common entry point methods.
+      #
+      # @param source [String] Ruby source code
+      # @return [Array<String>] Entry point method names
+      def detect_entry_points(source)
+        points = []
+        points << 'call'    if source.match?(/def (self\.)?call\b/)
+        points << 'perform' if source.match?(/def (self\.)?perform\b/)
+        points << 'execute' if source.match?(/def (self\.)?execute\b/)
+        points << 'run'     if source.match?(/def (self\.)?run\b/)
+        points << 'process' if source.match?(/def (self\.)?process\b/)
+        points.empty? ? ['unknown'] : points
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Dependency Extraction
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Build the dependency array using common dependency scanners.
+      #
+      # @param source [String] Ruby source code
+      # @return [Array<Hash>] Dependency hashes with :type, :target, :via
+      def extract_dependencies(source)
+        deps = scan_common_dependencies(source)
+        deps.uniq { |d| [d[:type], d[:target]] }
+      end
+    end
+  end
+end

data/lib/codebase_index/extractors/mailer_extractor.rb

@@ -0,0 +1,339 @@
+# frozen_string_literal: true
+
+require 'digest'
+require_relative 'ast_source_extraction'
+require_relative 'shared_utility_methods'
+require_relative 'shared_dependency_scanner'
+
+module CodebaseIndex
+  module Extractors
+    # MailerExtractor handles ActionMailer extraction.
+    #
+    # Mailers are important for understanding:
+    # - What triggers emails (traced via dependencies)
+    # - What data flows into emails
+    # - Template associations
+    #
+    # @example
+    #   extractor = MailerExtractor.new
+    #   units = extractor.extract_all
+    #   user_mailer = units.find { |u| u.identifier == "UserMailer" }
+    #
+    class MailerExtractor
+      include AstSourceExtraction
+      include SharedUtilityMethods
+      include SharedDependencyScanner
+
+      def initialize
+        @mailer_base = defined?(ApplicationMailer) ? ApplicationMailer : ActionMailer::Base
+      end
+
+      # Extract all mailers in the application
+      #
+      # @return [Array<ExtractedUnit>] List of mailer units
+      def extract_all
+        @mailer_base.descendants.map do |mailer|
+          extract_mailer(mailer)
+        end.compact
+      end
+
+      # Extract a single mailer
+      #
+      # @param mailer [Class] The mailer class
+      # @return [ExtractedUnit] The extracted unit
+      def extract_mailer(mailer)
+        return nil if mailer.name.nil?
+        return nil if mailer == ActionMailer::Base
+
+        file_path = source_file_for(mailer)
+
+        unit = ExtractedUnit.new(
+          type: :mailer,
+          identifier: mailer.name,
+          file_path: file_path
+        )
+
+        source = file_path && File.exist?(file_path) ? File.read(file_path) : ''
+
+        unit.namespace = extract_namespace(mailer)
+        unit.source_code = annotate_source(source, mailer)
+        unit.metadata = extract_metadata(mailer, source)
+        unit.dependencies = extract_dependencies(source)
+
+        # Create chunks for each mail action
+        unit.chunks = build_action_chunks(mailer, source)
+
+        unit
+      rescue StandardError => e
+        Rails.logger.error("Failed to extract mailer #{mailer.name}: #{e.message}")
+        nil
+      end
+
+      private
+
+      def source_file_for(mailer)
+        if mailer.instance_methods(false).any?
+          method = mailer.instance_methods(false).first
+          mailer.instance_method(method).source_location&.first
+        end || Rails.root.join("app/mailers/#{mailer.name.underscore}.rb").to_s
+      rescue StandardError
+        Rails.root.join("app/mailers/#{mailer.name.underscore}.rb").to_s
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Source Annotation
+      # ──────────────────────────────────────────────────────────────────────
+
+      def annotate_source(source, mailer)
+        actions = mailer.action_methods.to_a
+        default_from = begin
+          mailer.default[:from]
+        rescue StandardError
+          nil
+        end
+
+        <<~ANNOTATION
+          # ╔═══════════════════════════════════════════════════════════════════════╗
+          # ║ Mailer: #{mailer.name.ljust(60)}║
+          # ║ Actions: #{actions.first(5).join(', ').ljust(59)}║
+          # ║ Default From: #{(default_from || 'not set').to_s.ljust(54)}║
+          # ╚═══════════════════════════════════════════════════════════════════════╝
+
+          #{source}
+        ANNOTATION
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Metadata Extraction
+      # ──────────────────────────────────────────────────────────────────────
+
+      def extract_metadata(mailer, source)
+        actions = mailer.action_methods.to_a
+
+        {
+          # Actions (mail methods)
+          actions: actions,
+
+          # Default settings
+          defaults: extract_defaults(mailer),
+
+          # Delivery configuration
+          delivery_method: mailer.delivery_method,
+
+          # Callbacks
+          callbacks: extract_callbacks(mailer),
+
+          # Layout
+          layout: extract_layout(mailer, source),
+
+          # Helper modules
+          helpers: extract_helpers(source),
+
+          # Templates (if discoverable)
+          templates: discover_templates(mailer, actions),
+
+          # Metrics
+          action_count: actions.size,
+          loc: source.lines.count { |l| l.strip.present? && !l.strip.start_with?('#') }
+        }
+      end
+
+      def extract_defaults(mailer)
+        defaults = {}
+
+        begin
+          mailer_defaults = mailer.default
+          defaults[:from] = mailer_defaults[:from] if mailer_defaults[:from]
+          defaults[:reply_to] = mailer_defaults[:reply_to] if mailer_defaults[:reply_to]
+          defaults[:cc] = mailer_defaults[:cc] if mailer_defaults[:cc]
+          defaults[:bcc] = mailer_defaults[:bcc] if mailer_defaults[:bcc]
+        rescue StandardError
+          # Defaults not accessible
+        end
+
+        defaults
+      end
+
+      def extract_callbacks(mailer)
+        mailer._process_action_callbacks.map do |cb|
+          only, except, if_conds, unless_conds = extract_callback_conditions(cb)
+
+          result = {
+            type: :"#{cb.kind}_action",
+            filter: cb.filter.to_s
+          }
+          result[:only] = only if only.any?
+          result[:except] = except if except.any?
+          result[:if] = if_conds.join(', ') if if_conds.any?
+          result[:unless] = unless_conds.join(', ') if unless_conds.any?
+          result
+        end
+      rescue StandardError
+        []
+      end
+
+      # Extract :only/:except action lists and :if/:unless conditions from a callback.
+      #
+      # Modern Rails (4.2+) stores conditions in @if/@unless ivar arrays.
+      # ActionFilter objects hold action Sets; other conditions are procs/symbols.
+      #
+      # @param callback [ActiveSupport::Callbacks::Callback]
+      # @return [Array(Array<String>, Array<String>, Array<String>, Array<String>)]
+      #   [only_actions, except_actions, if_labels, unless_labels]
+      def extract_callback_conditions(callback)
+        if_conditions = callback.instance_variable_get(:@if) || []
+        unless_conditions = callback.instance_variable_get(:@unless) || []
+
+        only = []
+        except = []
+        if_labels = []
+        unless_labels = []
+
+        if_conditions.each do |cond|
+          actions = extract_action_filter_actions(cond)
+          if actions
+            only.concat(actions)
+          else
+            if_labels << condition_label(cond)
+          end
+        end
+
+        unless_conditions.each do |cond|
+          actions = extract_action_filter_actions(cond)
+          if actions
+            except.concat(actions)
+          else
+            unless_labels << condition_label(cond)
+          end
+        end
+
+        [only, except, if_labels, unless_labels]
+      end
+
+      # Extract action names from an ActionFilter-like condition object.
+      # Duck-types on the @actions ivar being a Set, avoiding dependence
+      # on private class names across Rails versions.
+      #
+      # @param condition [Object] A condition from the callback's @if/@unless array
+      # @return [Array<String>, nil] Action names, or nil if not an ActionFilter
+      def extract_action_filter_actions(condition)
+        return nil unless condition.instance_variable_defined?(:@actions)
+
+        actions = condition.instance_variable_get(:@actions)
+        return nil unless actions.is_a?(Set)
+
+        actions.to_a
+      end
+
+      # Human-readable label for a non-ActionFilter condition.
+      #
+      # @param condition [Object] A proc, symbol, or other condition
+      # @return [String]
+      def condition_label(condition)
+        case condition
+        when Symbol then ":#{condition}"
+        when Proc then 'Proc'
+        when String then condition
+        else condition.class.name
+        end
+      end
+
+      def extract_layout(mailer, source)
+        # From class definition
+        return ::Regexp.last_match(1) if source =~ /layout\s+['":](\w+)/
+
+        # From class method
+        begin
+          mailer._layout
+        rescue StandardError
+          nil
+        end
+      end
+
+      def extract_helpers(source)
+        helpers = []
+
+        source.scan(/helper\s+[:\s]?(\w+)/) do |helper|
+          helpers << helper[0]
+        end
+
+        source.scan(/include\s+(\w+Helper)/) do |helper|
+          helpers << helper[0]
+        end
+
+        helpers.uniq
+      end
+
+      def discover_templates(mailer, actions)
+        templates = {}
+        mailer_path = mailer.name.underscore
+
+        actions.each do |action|
+          view_paths = [
+            Rails.root.join("app/views/#{mailer_path}/#{action}.html.erb"),
+            Rails.root.join("app/views/#{mailer_path}/#{action}.text.erb"),
+            Rails.root.join("app/views/#{mailer_path}/#{action}.html.slim"),
+            Rails.root.join("app/views/#{mailer_path}/#{action}.text.slim")
+          ]
+
+          found = view_paths.select { |p| File.exist?(p) }
+                            .map { |p| p.to_s.sub("#{Rails.root}/", '') }
+
+          templates[action] = found if found.any?
+        end
+
+        templates
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Dependency Extraction
+      # ──────────────────────────────────────────────────────────────────────
+
+      def extract_dependencies(source)
+        deps = []
+        deps.concat(scan_model_dependencies(source))
+        deps.concat(scan_service_dependencies(source))
+
+        # URL helpers (indicates what resources emails link to)
+        source.scan(/(\w+)_(?:url|path)/).flatten.uniq.each do |route|
+          deps << { type: :route, target: route, via: :url_helper }
+        end
+
+        deps.uniq { |d| [d[:type], d[:target]] }
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Action Chunks
+      # ──────────────────────────────────────────────────────────────────────
+
+      def build_action_chunks(mailer, _source)
+        mailer.action_methods.filter_map do |action|
+          action_source = extract_action_source(mailer, action)
+          next if action_source.nil? || action_source.strip.empty?
+
+          templates = discover_templates(mailer, [action.to_s])[action.to_s] || []
+
+          chunk_content = <<~ACTION
+            # Mailer: #{mailer.name}
+            # Action: #{action}
+            # Templates: #{templates.any? ? templates.join(', ') : 'none found'}
+
+            #{action_source}
+          ACTION
+
+          {
+            chunk_type: :mail_action,
+            identifier: "#{mailer.name}##{action}",
+            content: chunk_content,
+            content_hash: Digest::SHA256.hexdigest(chunk_content),
+            metadata: {
+              parent: mailer.name,
+              action: action.to_s,
+              templates: templates
+            }
+          }
+        end
+      end
+    end
+  end
+end