codebase_index 0.1.0

data/lib/codebase_index/extractors/engine_extractor.rb

@@ -0,0 +1,204 @@
+# frozen_string_literal: true
+
+require_relative 'shared_utility_methods'
+
+module CodebaseIndex
+  module Extractors
+    # EngineExtractor handles Rails engine and mountable gem extraction via runtime introspection.
+    #
+    # Reads `Rails::Engine.subclasses` to discover engines, then inspects each engine's
+    # routes, mount point, and configuration. Each engine becomes one ExtractedUnit with
+    # metadata about its name, root path, mount point, route count, and isolation.
+    #
+    # @example
+    #   extractor = EngineExtractor.new
+    #   units = extractor.extract_all
+    #   devise = units.find { |u| u.identifier == "Devise::Engine" }
+    #
+    class EngineExtractor
+      include SharedUtilityMethods
+
+      def initialize
+        # No directories to scan — this is runtime introspection
+      end
+
+      # Extract all Rails engines as ExtractedUnits
+      #
+      # @return [Array<ExtractedUnit>] List of engine units
+      def extract_all
+        return [] unless engines_available?
+
+        engines = engine_subclasses
+        return [] if engines.empty?
+
+        mount_map = build_mount_map
+        engines.filter_map { |engine| extract_engine(engine, mount_map) }
+      end
+
+      private
+
+      # Check if Rails::Engine and the application routing table are available.
+      #
+      # @return [Boolean]
+      def engines_available?
+        defined?(Rails::Engine) &&
+          Rails.respond_to?(:application) &&
+          Rails.application.respond_to?(:routes)
+      end
+
+      # Retrieve Engine subclasses, compatible with Ruby 3.0+.
+      # Class#subclasses was added in Ruby 3.1; fall back to descendants filtering.
+      #
+      # @return [Array<Class>]
+      def engine_subclasses
+        if Rails::Engine.respond_to?(:subclasses)
+          Rails::Engine.subclasses
+        else
+          ObjectSpace.each_object(Class).select { |klass| klass < Rails::Engine }
+        end
+      end
+
+      # Build a mapping from engine class to mounted path by scanning app routes.
+      #
+      # @return [Hash{Class => String}] Engine class to mount path
+      def build_mount_map
+        map = {}
+        Rails.application.routes.routes.each do |route|
+          app = route.app
+          next unless engine_class?(app)
+
+          path = extract_mount_path(route)
+          map[app] = path if path
+        rescue StandardError
+          next
+        end
+        map
+      rescue StandardError
+        {}
+      end
+
+      # Check if an object is a Rails::Engine subclass.
+      #
+      # Uses duck-typing: checks for engine_name method which is defined on all
+      # Rails::Engine subclasses. Falls back to class hierarchy check.
+      #
+      # @param app [Object] The route app object
+      # @return [Boolean]
+      def engine_class?(app)
+        return true if app.is_a?(Class) && defined?(Rails::Engine) && app < Rails::Engine
+        return true if app.respond_to?(:engine_name) && app.respond_to?(:routes)
+
+        false
+      end
+
+      # Extract the mount path string from a route object.
+      #
+      # @param route [ActionDispatch::Journey::Route]
+      # @return [String, nil]
+      def extract_mount_path(route)
+        return nil unless route.respond_to?(:path) && route.path
+
+        spec = route.path
+        spec = spec.spec if spec.respond_to?(:spec)
+        path = spec.to_s
+        path.empty? ? nil : path
+      end
+
+      # Extract a single engine into an ExtractedUnit.
+      #
+      # @param engine [Class] A Rails::Engine subclass
+      # @param mount_map [Hash] Engine-to-path mapping
+      # @return [ExtractedUnit, nil]
+      def extract_engine(engine, mount_map)
+        name = engine.name
+        engine_name = engine.engine_name
+        root_path = engine.root.to_s
+        route_count = count_engine_routes(engine)
+        mounted_path = mount_map[engine]
+        isolated = engine.respond_to?(:isolated?) ? engine.isolated? : false
+        controllers = extract_engine_controllers(engine)
+
+        unit = ExtractedUnit.new(
+          type: :engine,
+          identifier: name,
+          file_path: nil
+        )
+
+        unit.namespace = extract_namespace(name)
+        unit.source_code = build_engine_source(name, engine_name, root_path, mounted_path, route_count, isolated)
+        unit.metadata = {
+          engine_name: engine_name,
+          root_path: root_path,
+          mounted_path: mounted_path,
+          route_count: route_count,
+          isolate_namespace: isolated,
+          controllers: controllers
+        }
+        unit.dependencies = build_engine_dependencies(controllers)
+
+        unit
+      rescue StandardError => e
+        Rails.logger.error("Failed to extract engine #{engine.name}: #{e.message}")
+        nil
+      end
+
+      # Count routes defined by an engine.
+      #
+      # @param engine [Class] A Rails::Engine subclass
+      # @return [Integer]
+      def count_engine_routes(engine)
+        engine.routes.routes.count
+      rescue StandardError
+        0
+      end
+
+      # Extract controller names from engine routes.
+      #
+      # @param engine [Class] A Rails::Engine subclass
+      # @return [Array<String>] Controller class names
+      def extract_engine_controllers(engine)
+        controllers = Set.new
+        engine.routes.routes.each do |route|
+          defaults = route.respond_to?(:defaults) ? route.defaults : {}
+          controller = defaults[:controller]
+          controllers << "#{controller.camelize}Controller" if controller
+        rescue StandardError
+          next
+        end
+        controllers.to_a
+      rescue StandardError
+        []
+      end
+
+      # Build a human-readable source representation of the engine.
+      #
+      # @param name [String] Engine class name
+      # @param engine_name [String] Engine short name
+      # @param root_path [String] Engine root directory
+      # @param mounted_path [String, nil] Mount path in host app
+      # @param route_count [Integer] Number of routes
+      # @param isolated [Boolean] Whether engine uses isolate_namespace
+      # @return [String]
+      def build_engine_source(name, engine_name, root_path, mounted_path, route_count, isolated)
+        lines = []
+        lines << "# Engine: #{name}"
+        lines << "# Name: #{engine_name}"
+        lines << "# Root: #{root_path}"
+        lines << "# Mounted at: #{mounted_path || '(not mounted)'}"
+        lines << "# Routes: #{route_count}"
+        lines << "# Isolated namespace: #{isolated}"
+        lines.join("\n")
+      end
+
+      # Build dependencies linking engine to its controllers.
+      #
+      # @param controllers [Array<String>] Controller class names
+      # @return [Array<Hash>]
+      def build_engine_dependencies(controllers)
+        controllers.map do |controller|
+          { type: :controller, target: controller, via: :engine_route }
+        end
+      end
+    end
+  end
+end

data/lib/codebase_index/extractors/event_extractor.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require_relative 'shared_utility_methods'
+require_relative 'shared_dependency_scanner'
+
+module CodebaseIndex
+  module Extractors
+    # EventExtractor discovers event publishing and subscribing patterns across the app.
+    #
+    # Scans +app/**/*.rb+ for two event system conventions:
+    # - ActiveSupport::Notifications: +instrument+ (publish) and +subscribe+ (consume)
+    # - Wisper: +publish+/+broadcast+ (publish) and +on(:event_name)+ (subscribe)
+    #
+    # Uses a two-pass approach:
+    # 1. Scan all files, collecting publishers and subscribers per event name
+    # 2. Merge by event name → one ExtractedUnit per unique event
+    #
+    # @example
+    #   extractor = EventExtractor.new
+    #   units = extractor.extract_all
+    #   event = units.find { |u| u.identifier == "order.completed" }
+    #   event.metadata[:publishers]  # => ["app/services/order_service.rb"]
+    #   event.metadata[:subscribers] # => ["app/listeners/order_listener.rb"]
+    #   event.metadata[:pattern]     # => :active_support
+    #
+    class EventExtractor
+      include SharedUtilityMethods
+      include SharedDependencyScanner
+
+      APP_DIRECTORIES = %w[app].freeze
+
+      def initialize
+        @directories = APP_DIRECTORIES.map { |d| Rails.root.join(d) }.select(&:directory?)
+      end
+
+      # Extract all event units using a two-pass approach.
+      #
+      # Pass 1: Collect publish/subscribe references across all app files.
+      # Pass 2: Merge by event name — one ExtractedUnit per unique event.
+      #
+      # @return [Array<ExtractedUnit>] One unit per unique event name
+      def extract_all
+        event_map = {}
+
+        @directories.flat_map { |dir| Dir[dir.join('**/*.rb')] }.each do |file_path|
+          scan_file(file_path, event_map)
+        end
+
+        event_map.filter_map { |event_name, data| build_unit(event_name, data) }
+      end
+
+      # Scan a single file for event publishing and subscribing patterns.
+      #
+      # Mutates +event_map+ in place, registering publishers and subscribers.
+      #
+      # @param file_path [String] Path to the Ruby file
+      # @param event_map [Hash] Mutable map of event_name => {publishers:, subscribers:, pattern:}
+      # @return [void]
+      def scan_file(file_path, event_map)
+        source = File.read(file_path)
+        scan_active_support_notifications(source, file_path, event_map)
+        scan_wisper_patterns(source, file_path, event_map)
+      rescue StandardError => e
+        Rails.logger.error("Failed to scan #{file_path} for events: #{e.message}")
+      end
+
+      private
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Pattern Detection
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Scan for ActiveSupport::Notifications instrument and subscribe patterns.
+      #
+      # @param source [String] Ruby source code
+      # @param file_path [String] File path
+      # @param event_map [Hash] Mutable event map
+      # @return [void]
+      def scan_active_support_notifications(source, file_path, event_map)
+        source.scan(/ActiveSupport::Notifications\.instrument\s*\(\s*["']([^"']+)["']/) do |m|
+          register_publisher(event_map, m[0], file_path, :active_support)
+        end
+
+        source.scan(/ActiveSupport::Notifications\.subscribe\s*\(\s*["']([^"']+)["']/) do |m|
+          register_subscriber(event_map, m[0], file_path, :active_support)
+        end
+      end
+
+      # Scan for Wisper event patterns.
+      #
+      # Publishers must have Wisper context in the file (include Wisper or use
+      # Wisper directly). Subscribers are detected via +.on(:event_name)+ chains.
+      #
+      # @param source [String] Ruby source code
+      # @param file_path [String] File path
+      # @param event_map [Hash] Mutable event map
+      # @return [void]
+      def scan_wisper_patterns(source, file_path, event_map)
+        if source.match?(/include\s+Wisper/)
+          source.scan(/\b(?:publish|broadcast)\s+:(\w+)/) do |m|
+            register_publisher(event_map, m[0], file_path, :wisper)
+          end
+        end
+
+        source.scan(/\.on\s*\(\s*:(\w+)/) do |m|
+          register_subscriber(event_map, m[0], file_path, :wisper)
+        end
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Event Map Mutation
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Register a publisher for an event name.
+      #
+      # @param event_map [Hash] Mutable event map
+      # @param event_name [String] Event name
+      # @param file_path [String] Publisher file path
+      # @param pattern [Symbol] :active_support or :wisper
+      # @return [void]
+      def register_publisher(event_map, event_name, file_path, pattern)
+        entry = event_map[event_name] ||= { publishers: [], subscribers: [], pattern: pattern }
+        entry[:publishers] << file_path unless entry[:publishers].include?(file_path)
+      end
+
+      # Register a subscriber for an event name.
+      #
+      # @param event_map [Hash] Mutable event map
+      # @param event_name [String] Event name
+      # @param file_path [String] Subscriber file path
+      # @param pattern [Symbol] :active_support or :wisper
+      # @return [void]
+      def register_subscriber(event_map, event_name, file_path, pattern)
+        entry = event_map[event_name] ||= { publishers: [], subscribers: [], pattern: pattern }
+        entry[:subscribers] << file_path unless entry[:subscribers].include?(file_path)
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Unit Construction
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Build an ExtractedUnit from accumulated event data.
+      #
+      # Returns nil if the event has neither publishers nor subscribers (no-op).
+      #
+      # @param event_name [String] Event name (used as the unit identifier)
+      # @param data [Hash] Accumulated publishers/subscribers/pattern
+      # @return [ExtractedUnit, nil]
+      def build_unit(event_name, data)
+        return nil if data[:publishers].empty? && data[:subscribers].empty?
+
+        file_path = data[:publishers].first || data[:subscribers].first
+        all_paths = (data[:publishers] + data[:subscribers]).uniq
+        combined_source = load_source_files(all_paths)
+
+        unit = ExtractedUnit.new(
+          type: :event,
+          identifier: event_name,
+          file_path: file_path
+        )
+
+        unit.source_code = build_source_annotation(event_name, data)
+        unit.metadata = {
+          event_name: event_name,
+          publishers: data[:publishers],
+          subscribers: data[:subscribers],
+          pattern: data[:pattern],
+          publisher_count: data[:publishers].size,
+          subscriber_count: data[:subscribers].size
+        }
+        unit.dependencies = build_dependencies(combined_source)
+        unit
+      end
+
+      # Load source from multiple files for dependency scanning.
+      #
+      # Silently skips files that cannot be read.
+      #
+      # @param file_paths [Array<String>] File paths to read
+      # @return [String] Combined source
+      def load_source_files(file_paths)
+        file_paths.filter_map do |path|
+          File.read(path)
+        rescue StandardError
+          nil
+        end.join("\n")
+      end
+
+      # Build annotated source annotation for the event unit.
+      #
+      # @param event_name [String] Event name
+      # @param data [Hash] Event data with publishers and subscribers
+      # @return [String]
+      def build_source_annotation(event_name, data)
+        lines = ["# Event: #{event_name} (#{data[:pattern]})"]
+        lines << "# Publishers: #{data[:publishers].join(', ')}" if data[:publishers].any?
+        lines << "# Subscribers: #{data[:subscribers].join(', ')}" if data[:subscribers].any?
+        lines.join("\n")
+      end
+
+      # Build dependencies by scanning combined source of publisher/subscriber files.
+      #
+      # @param combined_source [String] Combined source from all related files
+      # @return [Array<Hash>]
+      def build_dependencies(combined_source)
+        deps = scan_common_dependencies(combined_source)
+        deps.uniq { |d| [d[:type], d[:target]] }
+      end
+    end
+  end
+end

data/lib/codebase_index/extractors/factory_extractor.rb

@@ -0,0 +1,289 @@
+# frozen_string_literal: true
+
+require_relative 'shared_utility_methods'
+require_relative 'shared_dependency_scanner'
+
+module CodebaseIndex
+  module Extractors
+    # FactoryExtractor handles extraction of FactoryBot factory definitions.
+    #
+    # Scans spec/factories/ and test/factories/ for FactoryBot definitions
+    # and produces one ExtractedUnit per factory block. Uses a line-by-line
+    # state machine parser (never evals factory files).
+    #
+    # Supports: basic factories, explicit class override, traits, associations,
+    # sequences, callbacks, parent inheritance, transient attributes, and
+    # nested factory definitions (each becomes its own unit).
+    #
+    # @example
+    #   extractor = FactoryExtractor.new
+    #   units = extractor.extract_all
+    #   user = units.find { |u| u.identifier == "user" }
+    #   user.metadata[:traits] # => ["admin", "with_avatar"]
+    #
+    class FactoryExtractor
+      include SharedUtilityMethods
+      include SharedDependencyScanner
+
+      FACTORY_DIRECTORIES = %w[spec/factories test/factories].freeze
+
+      def initialize
+        @directories = FACTORY_DIRECTORIES.map { |d| Rails.root.join(d) }.select(&:directory?)
+      end
+
+      # Extract all factory definitions from all discovered directories.
+      #
+      # @return [Array<ExtractedUnit>] List of factory units
+      def extract_all
+        @directories.flat_map do |dir|
+          Dir[dir.join('**/*.rb')].flat_map { |file| extract_factory_file(file) }
+        end
+      end
+
+      # Extract factory definitions from a single factory file.
+      #
+      # Returns an Array because each file may contain multiple factory definitions.
+      #
+      # @param file_path [String] Path to the factory file
+      # @return [Array<ExtractedUnit>] List of factory units
+      def extract_factory_file(file_path)
+        return [] unless file_path.to_s.end_with?('.rb')
+
+        source = File.read(file_path)
+        factories = parse_factories(source)
+
+        factories.map { |factory_data| build_unit(factory_data, file_path, source) }
+      rescue StandardError => e
+        Rails.logger.error("Failed to extract factories from #{file_path}: #{e.message}")
+        []
+      end
+
+      private
+
+      # Parse factory definitions from source using a line-by-line state machine.
+      #
+      # Tracks factory nesting, traits, associations, sequences, callbacks, and
+      # transient attributes. Each factory block (including nested factories within
+      # a parent factory) produces one entry in the returned array.
+      #
+      # @param source [String] Factory file source code
+      # @return [Array<Hash>] Parsed factory data hashes
+      def parse_factories(source)
+        completed = []
+        factory_stack = []
+        depth = 0
+        in_transient = false
+        transient_depth = nil
+
+        source.lines.each_with_index do |line, index|
+          stripped = line.strip
+
+          # Factory definition — push new factory onto stack
+          if (factory_data = match_factory(stripped, depth, index + 1))
+            factory_stack.push(factory_data)
+            depth += 1
+            next
+          end
+
+          # Trait definition — record trait in current factory, open block
+          if (trait_match = stripped.match(/\Atrait\s+:(\w+)\s+do/))
+            factory_stack.last[:traits] << trait_match[1] if factory_stack.any?
+            depth += 1
+            next
+          end
+
+          # Transient block — start collecting transient attributes
+          if stripped.match?(/\Atransient\s+do/)
+            in_transient = true
+            transient_depth = depth
+            depth += 1
+            next
+          end
+
+          # Collect transient attribute names (word { ... } or word do)
+          if in_transient && factory_stack.any? && (attr_match = stripped.match(/\A(\w+)\s*(?:\{|do\b)/))
+            factory_stack.last[:transient_attributes] << attr_match[1]
+          end
+
+          # Association
+          if factory_stack.any? && (assoc_match = stripped.match(/\Aassociation\s+:(\w+)/))
+            factory_stack.last[:associations] << assoc_match[1]
+          end
+
+          # Sequence
+          if factory_stack.any? && (seq_match = stripped.match(/\Asequence\s*\(:(\w+)\)/))
+            factory_stack.last[:sequences] << seq_match[1]
+          end
+
+          # Callbacks: after(:hook), before(:hook), after_stub(:hook)
+          if factory_stack.any? && (cb_match = stripped.match(/\A(?:after|before|after_stub)\s*\([:'"](\w+)/))
+            factory_stack.last[:callbacks] << cb_match[1]
+          end
+
+          # Generic block openers — factory/trait/transient already handled above with next
+          if block_opener?(stripped)
+            depth += 1
+            next
+          end
+
+          next unless stripped == 'end'
+
+          depth -= 1
+
+          # Close transient block if we've returned to the depth where it was opened
+          if in_transient && depth == transient_depth
+            in_transient = false
+            transient_depth = nil
+          end
+
+          # Close factory if top factory was opened at this depth
+          next unless factory_stack.any? && depth == factory_stack.last[:open_depth]
+
+          completed << factory_stack.pop
+        end
+
+        completed
+      end
+
+      # Try to match a factory definition line and return initialized factory data.
+      #
+      # Handles:
+      #   factory :name do
+      #   factory :name, class: ClassName do
+      #   factory :name, class: 'ClassName' do
+      #   factory :name, parent: :other do
+      #
+      # @param line [String] Stripped source line
+      # @param depth [Integer] Current block depth when factory would be opened
+      # @param line_number [Integer] 1-based line number
+      # @return [Hash, nil] Initialized factory data or nil if not a factory line
+      def match_factory(line, depth, line_number)
+        return nil unless line.match?(/\Afactory\s+:/) && line.match?(/\bdo\b/)
+
+        name_match = line.match(/\Afactory\s+:(\w+)/)
+        return nil unless name_match
+
+        name = name_match[1]
+        options = {}
+
+        if (class_match = line.match(/\bclass:\s*['"]?([\w:]+)['"]?/))
+          options[:class_name] = class_match[1]
+        end
+
+        if (parent_match = line.match(/\bparent:\s*:(\w+)/))
+          options[:parent] = parent_match[1]
+        end
+
+        {
+          name: name,
+          class_name: options[:class_name] || classify(name),
+          parent_factory: options[:parent],
+          open_depth: depth,
+          line_number: line_number,
+          traits: [],
+          associations: [],
+          sequences: [],
+          callbacks: [],
+          transient_attributes: []
+        }
+      end
+
+      # Convert a snake_case factory name to a CamelCase class name.
+      #
+      # @param name [String] Snake_case factory name (e.g., "admin_user")
+      # @return [String] CamelCase class name (e.g., "AdminUser")
+      def classify(name)
+        name.split('_').map(&:capitalize).join
+      end
+
+      # Check if a stripped line opens a new block.
+      #
+      # Excludes factory, trait, and transient lines — those are handled
+      # explicitly in the main parser loop with depth tracking of their own.
+      #
+      # @param stripped [String] Stripped line content
+      # @return [Boolean]
+      def block_opener?(stripped)
+        return false if stripped.match?(/\Afactory\s+:/)
+        return false if stripped.match?(/\Atrait\s+:/)
+        return false if stripped.match?(/\Atransient\s+do/)
+        return true if stripped.match?(/\b(do|def|case|begin|class|module|while|until|for)\b.*(?<!\bend)\s*$/)
+
+        stripped.match?(/\A(if|unless)\b/)
+      end
+
+      # Build an ExtractedUnit from parsed factory data.
+      #
+      # @param factory_data [Hash] Parsed factory data
+      # @param file_path [String] Path to the factory file
+      # @param file_source [String] Full file source
+      # @return [ExtractedUnit]
+      def build_unit(factory_data, file_path, file_source)
+        unit = ExtractedUnit.new(
+          type: :factory,
+          identifier: factory_data[:name],
+          file_path: file_path
+        )
+
+        unit.source_code = build_source_annotation(factory_data, file_source)
+        unit.metadata = build_metadata(factory_data)
+        unit.dependencies = extract_dependencies(factory_data)
+
+        unit
+      end
+
+      # Build annotated source code for the unit.
+      #
+      # @param factory_data [Hash] Parsed factory data
+      # @param file_source [String] Full file source
+      # @return [String]
+      def build_source_annotation(factory_data, file_source)
+        header = "# Factory: #{factory_data[:name]} (model: #{factory_data[:class_name]})"
+        header += "\n# Parent: #{factory_data[:parent_factory]}" if factory_data[:parent_factory]
+        "#{header}\n#{file_source}"
+      end
+
+      # Build metadata hash for the unit.
+      #
+      # @param factory_data [Hash] Parsed factory data
+      # @return [Hash]
+      def build_metadata(factory_data)
+        {
+          factory_name: factory_data[:name],
+          model_class: factory_data[:class_name],
+          traits: factory_data[:traits],
+          associations: factory_data[:associations],
+          sequences: factory_data[:sequences],
+          parent_factory: factory_data[:parent_factory],
+          callbacks: factory_data[:callbacks].uniq,
+          transient_attributes: factory_data[:transient_attributes]
+        }
+      end
+
+      # Extract dependencies from factory data.
+      #
+      # Creates:
+      # - :model dependency (via :factory_for) linking to the modeled class
+      # - :factory dependency (via :factory_parent) for parent factory inheritance
+      # - :factory dependencies (via :factory_association) for each association
+      #
+      # @param factory_data [Hash] Parsed factory data
+      # @return [Array<Hash>]
+      def extract_dependencies(factory_data)
+        deps = []
+
+        deps << { type: :model, target: factory_data[:class_name], via: :factory_for }
+
+        if factory_data[:parent_factory]
+          deps << { type: :factory, target: factory_data[:parent_factory], via: :factory_parent }
+        end
+
+        factory_data[:associations].each do |assoc|
+          deps << { type: :factory, target: assoc, via: :factory_association }
+        end
+
+        deps.uniq { |d| [d[:type], d[:target]] }
+      end
+    end
+  end
+end