woods 1.0.0

data/lib/woods/extractors/service_extractor.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require_relative 'shared_utility_methods'
+require_relative 'shared_dependency_scanner'
+
+module Woods
+  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, '(?:services|interactors|operations|commands|use_cases)')
+
+        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
+
+      # ──────────────────────────────────────────────────────────────────────
+      # 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
+
+      # ──────────────────────────────────────────────────────────────────────
+      # 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_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/woods/extractors/shared_dependency_scanner.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+require_relative '../model_name_cache'
+
+module Woods
+  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/woods/extractors/shared_utility_methods.rb

@@ -0,0 +1,281 @@
+# frozen_string_literal: true
+
+module Woods
+  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
+      # Check whether a path points to application source (under app_root, but
+      # not inside vendor/ or node_modules/ directories).
+      #
+      # In Docker environments where Rails.root is `/app`, a naive
+      # `start_with?(app_root)` also matches vendor bundle paths like
+      # `/app/vendor/bundle/ruby/…`. This helper rejects those.
+      #
+      # @param path [String, nil] Absolute file path
+      # @param app_root [String] Rails.root.to_s
+      # @return [Boolean]
+      def app_source?(path, app_root)
+        return false unless path
+
+        path.start_with?(app_root) && !path.include?('/vendor/') && !path.include?('/node_modules/')
+      end
+
+      # Resolve the source file for a class using reliable introspection,
+      # filtered through {#app_source?} to reject vendor/gem paths.
+      #
+      # Tier order:
+      #   1. +const_source_location+ (returns the class definition site)
+      #   2. Instance method source locations (first match wins)
+      #   3. Class/singleton method source locations (first match wins)
+      #
+      # @param klass [Class, Module] The class to resolve
+      # @param app_root [String] Rails.root.to_s
+      # @param fallback [String] Path to return when resolution fails
+      # @return [String] Resolved source path or fallback
+      def resolve_source_location(klass, app_root:, fallback:)
+        # Tier 1: const_source_location (most reliable — returns class definition site)
+        if Object.respond_to?(:const_source_location) && klass.name
+          loc = Object.const_source_location(klass.name)&.first
+          return loc if app_source?(loc, app_root)
+        end
+
+        # Tier 2: Instance methods defined directly on this class
+        klass.instance_methods(false).each do |method_name|
+          loc = klass.instance_method(method_name).source_location&.first
+          return loc if app_source?(loc, app_root)
+        end
+
+        # Tier 3: Class/singleton methods defined on this class
+        klass.methods(false).each do |method_name|
+          loc = klass.method(method_name).source_location&.first
+          return loc if app_source?(loc, app_root)
+        end
+
+        fallback
+      rescue StandardError
+        fallback
+      end
+
+      # Extract the primary class name from source or fall back to a file path convention.
+      #
+      # @param file_path [String] Absolute path to the Ruby file
+      # @param source [String] Ruby source code
+      # @param dir_prefix [String] Regex fragment matching the app/ subdirectory to strip
+      #   (e.g., "policies", "validators", "(?:services|interactors|operations|commands|use_cases)")
+      # @return [String] The class name
+      def extract_class_name(file_path, source, dir_prefix)
+        return ::Regexp.last_match(1) if source =~ /^\s*class\s+([\w:]+)/
+
+        file_path.sub("#{Rails.root}/", '').sub(%r{^app/#{dir_prefix}/}, '').sub('.rb', '').camelize
+      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
+
+      # Skip module-only files (concerns, base modules without a class).
+      #
+      # @param source [String] Ruby source code
+      # @return [Boolean]
+      def skip_file?(source)
+        source.match?(/^\s*module\s+[\w:]+\s*$/) && !source.match?(/^\s*class\s+/)
+      end
+
+      # Extract custom error/exception class names defined inline.
+      #
+      # @param source [String] Ruby source code
+      # @return [Array<String>] Custom error class names
+      def extract_custom_errors(source)
+        source.scan(/class\s+(\w+(?:Error|Exception))\s*</).flatten
+      end
+
+      # Detect common entry point methods in a source file.
+      #
+      # @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
+
+      # 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
+
+      # 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 via regex.
+      #
+      # Parses the parameter list of the initialize method to determine
+      # parameter names, defaults, and whether they are keyword arguments.
+      #
+      # Note: PhlexExtractor and ViewComponentExtractor override this with a
+      # runtime-introspection version that takes a Class object instead of source
+      # text, providing richer type information (:req, :opt, :keyreq, :rest, etc.).
+      #
+      # @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