codebase_index 0.1.0

data/lib/codebase_index/extractors/service_extractor.rb

@@ -0,0 +1,254 @@
+# frozen_string_literal: true
+
+require_relative 'shared_utility_methods'
+require_relative 'shared_dependency_scanner'
+
+module CodebaseIndex
+  module Extractors
+    # ServiceExtractor handles service object extraction.
+    #
+    # Service objects often contain the most important business logic.
+    # Unlike models (which are discovered via ActiveRecord), services
+    # are discovered by scanning conventional directories.
+    #
+    # We extract:
+    # - Public interface (call/perform/execute methods)
+    # - Dependencies (what models/services/jobs they use)
+    # - Error classes (custom exceptions defined)
+    # - Input/output patterns
+    #
+    # @example
+    #   extractor = ServiceExtractor.new
+    #   units = extractor.extract_all
+    #   checkout = units.find { |u| u.identifier == "CheckoutService" }
+    #
+    class ServiceExtractor
+      include SharedUtilityMethods
+      include SharedDependencyScanner
+
+      # Directories to scan for service objects
+      SERVICE_DIRECTORIES = %w[
+        app/services
+        app/interactors
+        app/operations
+        app/commands
+        app/use_cases
+      ].freeze
+
+      def initialize
+        @directories = SERVICE_DIRECTORIES.map { |d| Rails.root.join(d) }
+                                          .select(&:directory?)
+      end
+
+      # Extract all service objects
+      #
+      # @return [Array<ExtractedUnit>] List of service units
+      def extract_all
+        @directories.flat_map do |dir|
+          Dir[dir.join('**/*.rb')].filter_map do |file|
+            extract_service_file(file)
+          end
+        end
+      end
+
+      # Extract a single service file
+      #
+      # @param file_path [String] Path to the service file
+      # @return [ExtractedUnit, nil] The extracted unit or nil if not a service
+      def extract_service_file(file_path)
+        source = File.read(file_path)
+        class_name = extract_class_name(file_path, source)
+
+        return nil unless class_name
+        return nil if skip_file?(source)
+
+        unit = ExtractedUnit.new(
+          type: :service,
+          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, file_path)
+        unit.dependencies = extract_dependencies(source)
+
+        unit
+      rescue StandardError => e
+        Rails.logger.error("Failed to extract service #{file_path}: #{e.message}")
+        nil
+      end
+
+      private
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Class Discovery
+      # ──────────────────────────────────────────────────────────────────────
+
+      def extract_class_name(file_path, source)
+        # Try to extract from source first (handles nested modules)
+        return ::Regexp.last_match(1) if source =~ /^\s*class\s+([\w:]+)/
+
+        # Fall back to convention
+        relative_path = file_path.sub("#{Rails.root}/", '')
+
+        # app/services/payments/stripe_service.rb -> Payments::StripeService
+        relative_path
+          .sub(%r{^app/(services|interactors|operations|commands|use_cases)/}, '')
+          .sub('.rb', '')
+          .camelize
+      end
+
+      def skip_file?(source)
+        # Skip module-only files (concerns, base modules)
+        source.match?(/^\s*module\s+\w+\s*$/) && !source.match?(/^\s*class\s+/)
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Source Annotation
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Add annotations to help with retrieval
+      def annotate_source(source, class_name)
+        entry_points = detect_entry_points(source)
+
+        annotation = <<~ANNOTATION
+          # ╔═══════════════════════════════════════════════════════════════════════╗
+          # ║ Service: #{class_name.ljust(60)}║
+          # ║ Entry Points: #{entry_points.join(', ').ljust(55)}║
+          # ╚═══════════════════════════════════════════════════════════════════════╝
+
+        ANNOTATION
+
+        annotation + source
+      end
+
+      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
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Metadata Extraction
+      # ──────────────────────────────────────────────────────────────────────
+
+      def extract_metadata(source, _class_name, file_path)
+        {
+          # Entry points
+          public_methods: extract_public_methods(source),
+          entry_points: detect_entry_points(source),
+          class_methods: extract_class_methods(source),
+
+          # Patterns
+          is_callable: source.match?(/def (self\.)?call\b/),
+          is_interactor: source.match?(/include\s+Interactor/),
+          uses_dry_monads: source.match?(/include\s+Dry::Monads/),
+
+          # Dependency injection
+          initialize_params: extract_initialize_params(source),
+          injected_dependencies: extract_injected_deps(source),
+
+          # Error handling
+          custom_errors: extract_custom_errors(source),
+          rescues: extract_rescue_handlers(source),
+
+          # Return patterns
+          return_type: infer_return_type(source),
+
+          # Metrics
+          loc: source.lines.count { |l| l.strip.present? && !l.strip.start_with?('#') },
+          method_count: source.scan(/def\s+(?:self\.)?\w+/).size,
+          complexity: estimate_complexity(source),
+
+          # Directory context (what kind of service pattern)
+          service_type: infer_service_type(file_path)
+        }
+      end
+
+      def extract_injected_deps(source)
+        # Look for attr_reader/accessor that match common dependency patterns
+        deps = []
+
+        source.scan(/attr_(?:reader|accessor)\s+(.+)/) do |match|
+          match[0].scan(/:(\w+)/).flatten.each do |attr|
+            deps << attr if attr.match?(/service|repository|client|adapter|gateway|notifier|mailer/)
+          end
+        end
+
+        # Also look for initialize assignments
+        source.scan(/@(\w+)\s*=\s*(\w+)/) do |ivar, value|
+          deps << ivar if value.match?(/Service|Client|Repository|Adapter|Gateway/)
+        end
+
+        deps.uniq
+      end
+
+      def extract_custom_errors(source)
+        source.scan(/class\s+(\w+(?:Error|Exception))\s*</).flatten
+      end
+
+      def extract_rescue_handlers(source)
+        source.scan(/rescue\s+([\w:]+)/).flatten.uniq
+      end
+
+      def infer_return_type(source)
+        return :dry_monad if source.match?(/Success\(|Failure\(/)
+        return :result_object if source.match?(/Result\.new|OpenStruct\.new/)
+        return :boolean if source.match?(/def call.*?(?:true|false)\s*$/m)
+
+        :unknown
+      end
+
+      def estimate_complexity(source)
+        # Simple cyclomatic complexity estimate
+        branches = source.scan(/\b(?:if|unless|elsif|when|while|until|for|rescue|&&|\|\|)\b/).size
+        branches + 1
+      end
+
+      def infer_service_type(file_path)
+        case file_path
+        when /interactors/ then :interactor
+        when /operations/ then :operation
+        when /commands/ then :command
+        when /use_cases/ then :use_case
+        else :service
+        end
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Dependency Extraction
+      # ──────────────────────────────────────────────────────────────────────
+
+      def extract_dependencies(source)
+        deps = scan_common_dependencies(source)
+
+        # Interactors
+        source.scan(/(\w+Interactor)(?:\.|::)/).flatten.uniq.each do |interactor|
+          deps << { type: :interactor, target: interactor, via: :code_reference }
+        end
+
+        # External API clients
+        source.scan(/(\w+Client)(?:\.|::new)/).flatten.uniq.each do |client|
+          deps << { type: :api_client, target: client, via: :code_reference }
+        end
+
+        # HTTP calls
+        if source.match?(/HTTParty|Faraday|RestClient|Net::HTTP/)
+          deps << { type: :external, target: :http_api, via: :code_reference }
+        end
+
+        # Redis
+        if source.match?(/Redis\.current|REDIS|Sidekiq\.redis/)
+          deps << { type: :infrastructure, target: :redis, via: :code_reference }
+        end
+
+        deps.uniq { |d| [d[:type], d[:target]] }
+      end
+    end
+  end
+end

data/lib/codebase_index/extractors/shared_dependency_scanner.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative '../model_name_cache'
+
+module CodebaseIndex
+  module Extractors
+    # Common dependency scanning patterns shared across extractors.
+    #
+    # Most extractors scan source code for the same four dependency types:
+    # model references (via ModelNameCache), service objects, background jobs,
+    # and mailers. This module centralizes those scanning patterns.
+    #
+    # Individual scan methods accept an optional +:via+ parameter so
+    # extractors can customize the relationship label (e.g., +:serialization+
+    # instead of the default +:code_reference+).
+    #
+    # @example
+    #   class FooExtractor
+    #     include SharedDependencyScanner
+    #
+    #     def extract_dependencies(source)
+    #       deps = scan_common_dependencies(source)
+    #       deps << { type: :custom, target: "Bar", via: :special }
+    #       deps.uniq { |d| [d[:type], d[:target]] }
+    #     end
+    #   end
+    #
+    module SharedDependencyScanner
+      # Scan for ActiveRecord model references using the precomputed regex.
+      #
+      # @param source [String] Ruby source code to scan
+      # @param via [Symbol] Relationship label (default: :code_reference)
+      # @return [Array<Hash>] Dependency hashes with :type, :target, :via
+      def scan_model_dependencies(source, via: :code_reference)
+        source.scan(ModelNameCache.model_names_regex).uniq.map do |model_name|
+          { type: :model, target: model_name, via: via }
+        end
+      end
+
+      # Scan for service object references (e.g., FooService.call, FooService::new).
+      #
+      # @param source [String] Ruby source code to scan
+      # @param via [Symbol] Relationship label (default: :code_reference)
+      # @return [Array<Hash>] Dependency hashes
+      def scan_service_dependencies(source, via: :code_reference)
+        source.scan(/(\w+Service)(?:\.|::)/).flatten.uniq.map do |service|
+          { type: :service, target: service, via: via }
+        end
+      end
+
+      # Scan for background job references (e.g., FooJob.perform_later).
+      #
+      # @param source [String] Ruby source code to scan
+      # @param via [Symbol] Relationship label (default: :code_reference)
+      # @return [Array<Hash>] Dependency hashes
+      def scan_job_dependencies(source, via: :code_reference)
+        source.scan(/(\w+Job)\.perform/).flatten.uniq.map do |job|
+          { type: :job, target: job, via: via }
+        end
+      end
+
+      # Scan for mailer references (e.g., UserMailer.welcome_email).
+      #
+      # @param source [String] Ruby source code to scan
+      # @param via [Symbol] Relationship label (default: :code_reference)
+      # @return [Array<Hash>] Dependency hashes
+      def scan_mailer_dependencies(source, via: :code_reference)
+        source.scan(/(\w+Mailer)\./).flatten.uniq.map do |mailer|
+          { type: :mailer, target: mailer, via: via }
+        end
+      end
+
+      # Scan for all common dependency types and return a deduplicated array.
+      #
+      # Combines model, service, job, and mailer scans. Use this when an
+      # extractor needs all four standard dependency types with the default
+      # +:code_reference+ via label.
+      #
+      # @param source [String] Ruby source code to scan
+      # @return [Array<Hash>] Deduplicated dependency hashes
+      def scan_common_dependencies(source)
+        deps = []
+        deps.concat(scan_model_dependencies(source))
+        deps.concat(scan_service_dependencies(source))
+        deps.concat(scan_job_dependencies(source))
+        deps.concat(scan_mailer_dependencies(source))
+        deps.uniq { |d| [d[:type], d[:target]] }
+      end
+    end
+  end
+end

data/lib/codebase_index/extractors/shared_utility_methods.rb

@@ -0,0 +1,99 @@
+# frozen_string_literal: true
+
+module CodebaseIndex
+  module Extractors
+    # Utility methods shared across multiple extractors.
+    #
+    # Provides common helpers for namespace extraction, public method
+    # scanning, class method scanning, and initialize parameter parsing.
+    # These methods are duplicated across 4-11 extractors; this module
+    # centralizes them.
+    #
+    # @example
+    #   class FooExtractor
+    #     include SharedUtilityMethods
+    #
+    #     def extract_foo(klass)
+    #       namespace = extract_namespace(klass)
+    #       # ...
+    #     end
+    #   end
+    #
+    module SharedUtilityMethods
+      # Extract namespace from a class name string or class object.
+      #
+      # Handles both string input (e.g., "Payments::StripeService")
+      # and class object input (e.g., a Controller class).
+      #
+      # @param name_or_object [String, Class, Module] A class name or class object
+      # @return [String, nil] The namespace, or nil if top-level
+      def extract_namespace(name_or_object)
+        name = name_or_object.is_a?(String) ? name_or_object : name_or_object.name
+        parts = name.split('::')
+        parts.size > 1 ? parts[0..-2].join('::') : nil
+      end
+
+      # Extract public instance and class methods from source code.
+      #
+      # Walks source line-by-line tracking private/protected visibility.
+      # Returns method names that are in public scope and don't start with underscore.
+      #
+      # @param source [String] Ruby source code
+      # @return [Array<String>] Public method names
+      def extract_public_methods(source)
+        methods = []
+        in_private = false
+        in_protected = false
+
+        source.each_line do |line|
+          stripped = line.strip
+
+          in_private = true if stripped == 'private'
+          in_protected = true if stripped == 'protected'
+          in_private = false if stripped == 'public'
+          in_protected = false if stripped == 'public'
+
+          if !in_private && !in_protected && stripped =~ /def\s+((?:self\.)?\w+[?!=]?)/
+            method_name = ::Regexp.last_match(1)
+            methods << method_name unless method_name.start_with?('_')
+          end
+        end
+
+        methods
+      end
+
+      # Extract class-level (self.) method names from source code.
+      #
+      # @param source [String] Ruby source code
+      # @return [Array<String>] Class method names
+      def extract_class_methods(source)
+        source.scan(/def\s+self\.(\w+[?!=]?)/).flatten
+      end
+
+      # Extract initialize parameters from source code.
+      #
+      # Parses the parameter list of the initialize method to determine
+      # parameter names, defaults, and whether they are keyword arguments.
+      #
+      # @param source [String] Ruby source code
+      # @return [Array<Hash>] Parameter info hashes with :name, :has_default, :keyword
+      def extract_initialize_params(source)
+        init_match = source.match(/def\s+initialize\s*\((.*?)\)/m)
+        return [] unless init_match
+
+        params_str = init_match[1]
+        params = []
+
+        params_str.scan(/(\w+)(?::\s*([^,\n]+))?/) do |name, default|
+          params << {
+            name: name,
+            has_default: !default.nil?,
+            keyword: params_str.include?("#{name}:")
+          }
+        end
+
+        params
+      end
+    end
+  end
+end