woods 1.0.0

data/lib/woods/extractors/caching_extractor.rb

@@ -0,0 +1,261 @@
+# frozen_string_literal: true
+
+require_relative 'shared_utility_methods'
+require_relative 'shared_dependency_scanner'
+
+module Woods
+  module Extractors
+    # CachingExtractor detects caching usage across controllers, models, and views.
+    #
+    # Scans `app/controllers/**/*.rb`, `app/models/**/*.rb`, and
+    # `app/views/**/*.erb` for cache-related patterns: Rails.cache.*,
+    # caches_action, fragment cache blocks, cache_key, cache_version,
+    # and expires_in. Produces one unit per file that contains any
+    # cache calls, identifying the strategy and TTL patterns.
+    #
+    # @example
+    #   extractor = CachingExtractor.new
+    #   units = extractor.extract_all
+    #   ctrl = units.find { |u| u.identifier == "app/controllers/products_controller.rb" }
+    #   ctrl.metadata[:cache_strategy]  # => :low_level
+    #   ctrl.metadata[:cache_calls].size # => 3
+    #
+    class CachingExtractor
+      include SharedUtilityMethods
+      include SharedDependencyScanner
+
+      # File glob patterns to scan
+      SCAN_PATTERNS = {
+        controller: 'app/controllers/**/*.rb',
+        model: 'app/models/**/*.rb',
+        view: 'app/views/**/*.erb'
+      }.freeze
+
+      # Patterns that indicate cache usage, grouped by type
+      CACHE_PATTERNS = {
+        fetch: /Rails\.cache\.fetch\s*[(\[]/,
+        read: /Rails\.cache\.read\s*[(\[]/,
+        write: /Rails\.cache\.write\s*[(\[]/,
+        delete: /Rails\.cache\.delete\s*[(\[]/,
+        exist: /Rails\.cache\.exist\?\s*[(\[]/,
+        caches_action: /\bcaches_action\b/,
+        fragment: /\bcache\s+.*?\bdo\b|\bcache\s+do\b|\bcache\s*\(/,
+        cache_key: /\bcache_key\b/,
+        cache_version: /\bcache_version\b/
+      }.freeze
+
+      # Patterns for extracting TTL values
+      TTL_PATTERN = /expires_in:\s*([^,\n)]+)/
+
+      # Key-pattern regex (first argument to Rails.cache.*)
+      KEY_PATTERN = /Rails\.cache\.(?:fetch|read|write|delete|exist\?)\s*[(\[]?\s*([^,\n)\]]+)/
+
+      def initialize
+        @rails_root = Rails.root
+      end
+
+      # Extract caching units from all scanned files.
+      #
+      # @return [Array<ExtractedUnit>] One unit per file with cache calls
+      def extract_all
+        units = []
+
+        SCAN_PATTERNS.each do |file_type, pattern|
+          Dir[@rails_root.join(pattern)].each do |file|
+            unit = extract_caching_file(file, file_type)
+            units << unit if unit
+          end
+        end
+
+        units
+      end
+
+      # Extract a single file for caching patterns.
+      #
+      # Returns nil if the file contains no cache calls.
+      #
+      # @param file_path [String] Absolute path to the file
+      # @param file_type [Symbol] :controller, :model, or :view
+      # @return [ExtractedUnit, nil] The unit or nil if no cache usage
+      def extract_caching_file(file_path, file_type = nil)
+        source = File.read(file_path)
+
+        return nil unless cache_usage?(source)
+
+        file_type ||= infer_file_type(file_path)
+        identifier = relative_path(file_path)
+
+        unit = ExtractedUnit.new(
+          type: :caching,
+          identifier: identifier,
+          file_path: file_path
+        )
+
+        unit.namespace   = nil
+        unit.source_code = annotate_source(source, identifier, file_type)
+        unit.metadata    = extract_metadata(source, file_type)
+        unit.dependencies = extract_dependencies(source)
+
+        unit
+      rescue StandardError => e
+        Rails.logger.error("Failed to extract caching info from #{file_path}: #{e.message}")
+        nil
+      end
+
+      private
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Detection
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Check whether the source contains any cache calls.
+      #
+      # @param source [String] Ruby or ERB source
+      # @return [Boolean]
+      def cache_usage?(source)
+        CACHE_PATTERNS.values.any? { |pattern| source.match?(pattern) }
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Source Annotation
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Prepend a summary annotation header to the source.
+      #
+      # @param source [String] Source code
+      # @param identifier [String] Relative file path identifier
+      # @param file_type [Symbol] :controller, :model, or :view
+      # @return [String] Annotated source
+      def annotate_source(source, identifier, file_type)
+        annotation = <<~ANNOTATION
+          # ╔═══════════════════════════════════════════════════════════════════════╗
+          # ║ Caching: #{identifier.ljust(59)}║
+          # ║ File type: #{file_type.to_s.ljust(57)}║
+          # ╚═══════════════════════════════════════════════════════════════════════╝
+
+        ANNOTATION
+
+        annotation + source
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Metadata Extraction
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Build the metadata hash for a caching unit.
+      #
+      # @param source [String] Source code
+      # @param file_type [Symbol] :controller, :model, or :view
+      # @return [Hash] Caching metadata
+      def extract_metadata(source, file_type)
+        cache_calls = extract_cache_calls(source)
+        {
+          cache_calls: cache_calls,
+          cache_strategy: infer_cache_strategy(source, cache_calls),
+          file_type: file_type,
+          loc: source.lines.count { |l| l.strip.length.positive? && !l.strip.start_with?('#') }
+        }
+      end
+
+      # Extract individual cache call entries from source.
+      #
+      # Each entry has :type, :key_pattern, and :ttl.
+      #
+      # @param source [String] Source code
+      # @return [Array<Hash>] Cache call descriptors
+      def extract_cache_calls(source)
+        calls = []
+
+        CACHE_PATTERNS.each do |type, pattern|
+          source.scan(pattern) do
+            key = extract_key_pattern(source, type)
+            ttl = extract_ttl(source)
+            calls << { type: type, key_pattern: key, ttl: ttl }
+          end
+        end
+
+        calls
+      end
+
+      # Extract the key pattern for a Rails.cache call.
+      #
+      # Returns a simplified string representation of the first argument.
+      #
+      # @param source [String] Source code
+      # @param type [Symbol] The cache call type
+      # @return [String, nil] The key pattern or nil
+      def extract_key_pattern(source, type)
+        return nil unless %i[fetch read write delete exist].include?(type)
+
+        match = source.match(KEY_PATTERN)
+        match ? match[1].strip[0, 60] : nil
+      end
+
+      # Extract TTL value from expires_in option.
+      #
+      # @param source [String] Source code
+      # @return [String, nil] The TTL expression or nil
+      def extract_ttl(source)
+        match = source.match(TTL_PATTERN)
+        match ? match[1].strip : nil
+      end
+
+      # Infer the caching strategy from the call types present.
+      #
+      # @param source [String] Source code
+      # @param cache_calls [Array<Hash>] Extracted cache calls
+      # @return [Symbol] :fragment, :action, :low_level, or :mixed
+      def infer_cache_strategy(source, _cache_calls)
+        has_action    = source.match?(CACHE_PATTERNS[:caches_action])
+        has_fragment  = source.match?(CACHE_PATTERNS[:fragment])
+        has_low_level = source.match?(/Rails\.cache\.(?:fetch|read|write)/)
+
+        active_strategies = [has_action, has_fragment, has_low_level].count(true)
+
+        return :mixed if active_strategies > 1
+        return :action if has_action
+        return :fragment if has_fragment
+        return :low_level if has_low_level
+
+        :unknown
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Helpers
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Infer the file type from the file path.
+      #
+      # @param file_path [String] Absolute path to the file
+      # @return [Symbol] :controller, :model, or :view
+      def infer_file_type(file_path)
+        case file_path
+        when %r{app/controllers/} then :controller
+        when %r{app/models/}      then :model
+        when %r{app/views/}       then :view
+        else :unknown
+        end
+      end
+
+      # Compute the relative path from Rails root.
+      #
+      # @param file_path [String] Absolute path
+      # @return [String] Relative path (e.g., "app/controllers/products_controller.rb")
+      def relative_path(file_path)
+        file_path.sub("#{@rails_root}/", '')
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Dependency Extraction
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Build the dependency array by scanning source for common references.
+      #
+      # @param source [String] Source code
+      # @return [Array<Hash>] Dependency hashes with :type, :target, :via
+      def extract_dependencies(source)
+        scan_common_dependencies(source)
+      end
+    end
+  end
+end

data/lib/woods/extractors/callback_analyzer.rb

@@ -0,0 +1,246 @@
+# frozen_string_literal: true
+
+require 'set'
+require_relative '../ast/parser'
+require_relative '../flow_analysis/operation_extractor'
+
+module Woods
+  module Extractors
+    # Analyzes callback method bodies to detect side effects.
+    #
+    # Given a model's composite source code (with inlined concerns) and its
+    # callback metadata, this analyzer finds each callback method body and
+    # classifies its side effects: column writes, job enqueues, service calls,
+    # mailer triggers, and database reads.
+    #
+    # @example
+    #   analyzer = CallbackAnalyzer.new(
+    #     source_code: model_source,
+    #     column_names: %w[email status name]
+    #   )
+    #   enriched = analyzer.analyze(callback_hash)
+    #   enriched[:side_effects][:columns_written] #=> ["email"]
+    #
+    class CallbackAnalyzer
+      # Database query methods that indicate a read operation.
+      DB_READ_METHODS = %w[find where pluck first last].freeze
+
+      # Methods that write a single column, taking column name as first argument.
+      SINGLE_COLUMN_WRITERS = %w[update_column write_attribute].freeze
+
+      # Methods that write multiple columns via keyword arguments.
+      MULTI_COLUMN_WRITERS = %w[update_columns assign_attributes].freeze
+
+      # Async enqueue methods that indicate a job is being dispatched.
+      ASYNC_METHODS = %w[perform_later perform_async perform_in perform_at].freeze
+
+      # Pre-compiled regex patterns (avoid dynamic regex construction in hot loops)
+      SINGLE_COLUMN_WRITER_PATTERNS = SINGLE_COLUMN_WRITERS.to_h do |w|
+        [w, /\b#{Regexp.escape(w)}\s*\(?\s*[:'"](\w+)/]
+      end.freeze
+
+      MULTI_COLUMN_WRITER_PATTERNS = MULTI_COLUMN_WRITERS.to_h do |w|
+        [w, /\b#{Regexp.escape(w)}\s*\(([^)]+)\)/m]
+      end.freeze
+
+      ASYNC_PATTERN = /(\w+(?:Job|Worker))\.(?:#{ASYNC_METHODS.map { |m| Regexp.escape(m) }.join('|')})/
+
+      DB_READ_PATTERNS = DB_READ_METHODS.to_h do |m|
+        [m, /\.#{Regexp.escape(m)}\b/]
+      end.freeze
+
+      # @param source_code [String] Composite model source (with inlined concerns)
+      # @param column_names [Array<String>] Model's database column names
+      def initialize(source_code:, column_names: [])
+        @source_code = source_code
+        @column_names = column_names.map(&:to_s)
+        @parser = Ast::Parser.new
+        @operation_extractor = FlowAnalysis::OperationExtractor.new
+        @parsed_root = safe_parse
+      end
+
+      # Analyze a single callback and enrich it with side-effect data.
+      #
+      # Finds the callback's method body in the source, scans it for
+      # side effects, and returns the original callback hash with an
+      # added :side_effects key.
+      #
+      # @param callback_hash [Hash] Callback metadata from ModelExtractor:
+      #   { type:, filter:, kind:, conditions: }
+      # @return [Hash] The callback hash with an added :side_effects key
+      def analyze(callback_hash)
+        filter = callback_hash[:filter].to_s
+        method_node = find_method_node(filter)
+
+        return callback_hash.merge(side_effects: empty_side_effects) if method_node.nil?
+
+        method_source = method_source_from_node(method_node)
+        return callback_hash.merge(side_effects: empty_side_effects) if method_source.nil?
+
+        callback_hash.merge(
+          side_effects: {
+            columns_written: detect_columns_written(method_source),
+            jobs_enqueued: detect_jobs_enqueued(method_source),
+            services_called: detect_services_called(method_source),
+            mailers_triggered: detect_mailers_triggered(method_source),
+            database_reads: detect_database_reads(method_source),
+            operations: extract_operations(method_node)
+          }
+        )
+      end
+
+      private
+
+      # Parse source code safely, returning nil on failure.
+      #
+      # @return [Ast::Node, nil]
+      def safe_parse
+        @parser.parse(@source_code)
+      rescue StandardError
+        nil
+      end
+
+      # Find a method definition node by name in the cached AST.
+      #
+      # @param method_name [String]
+      # @return [Ast::Node, nil]
+      def find_method_node(method_name)
+        return nil unless @parsed_root
+        return nil if method_name.empty? || !valid_method_name?(method_name)
+
+        @parsed_root.find_all(:def).find do |node|
+          node.method_name == method_name
+        end
+      end
+
+      # Extract the raw source text of a method from its AST node.
+      #
+      # @param node [Ast::Node]
+      # @return [String, nil]
+      def method_source_from_node(node)
+        return node.source if node.source
+
+        return nil unless node.line && node.end_line
+
+        lines = @source_code.lines
+        start_idx = node.line - 1
+        end_idx = node.end_line - 1
+        return nil if start_idx.negative? || end_idx >= lines.length
+
+        lines[start_idx..end_idx].join
+      end
+
+      # Check if a filter string looks like a valid Ruby method name.
+      # Rejects proc/lambda string representations and other non-method filters.
+      #
+      # @param name [String]
+      # @return [Boolean]
+      def valid_method_name?(name)
+        name.match?(/\A[a-z_]\w*[!?=]?\z/i)
+      end
+
+      # Detect columns written by the callback method.
+      #
+      # Scans for self.col= assignments, update_column, update_columns,
+      # write_attribute, and assign_attributes calls, cross-referencing
+      # against the model's known column_names.
+      #
+      # @param method_source [String]
+      # @return [Array<String>]
+      def detect_columns_written(method_source)
+        columns = Set.new
+
+        # Pattern: self.col = value (direct assignment, not ==)
+        method_source.scan(/self\.(\w+)\s*=(?!=)/).flatten.each do |col|
+          columns << col if @column_names.include?(col)
+        end
+
+        # Pattern: update_column(:col, ...) / write_attribute(:col, ...)
+        SINGLE_COLUMN_WRITER_PATTERNS.each_value do |pattern|
+          method_source.scan(pattern).flatten.each do |col|
+            columns << col if @column_names.include?(col)
+          end
+        end
+
+        # Pattern: update_columns(col: ...) / assign_attributes(col: ...)
+        MULTI_COLUMN_WRITER_PATTERNS.each_value do |pattern|
+          method_source.scan(pattern).each do |match|
+            match[0].scan(/\b(\w+)\s*:(?!:)/).flatten.each do |col|
+              columns << col if @column_names.include?(col)
+            end
+          end
+        end
+
+        columns.to_a.sort
+      end
+
+      # Detect jobs enqueued by the callback method.
+      #
+      # Matches Job/Worker classes calling async dispatch methods.
+      #
+      # @param method_source [String]
+      # @return [Array<String>]
+      def detect_jobs_enqueued(method_source)
+        method_source.scan(ASYNC_PATTERN).flatten.uniq.sort
+      end
+
+      # Detect service objects called by the callback method.
+      #
+      # Matches classes ending in Service followed by a method call.
+      #
+      # @param method_source [String]
+      # @return [Array<String>]
+      def detect_services_called(method_source)
+        method_source.scan(/(\w+Service)(?:\.|::)/).flatten.uniq.sort
+      end
+
+      # Detect mailers triggered by the callback method.
+      #
+      # Matches classes ending in Mailer followed by a method call.
+      #
+      # @param method_source [String]
+      # @return [Array<String>]
+      def detect_mailers_triggered(method_source)
+        method_source.scan(/(\w+Mailer)\./).flatten.uniq.sort
+      end
+
+      # Detect database read operations in the callback method.
+      #
+      # Checks for common ActiveRecord query methods called via dot notation.
+      #
+      # @param method_source [String]
+      # @return [Array<String>]
+      def detect_database_reads(method_source)
+        DB_READ_PATTERNS.filter_map do |method, pattern|
+          method if method_source.match?(pattern)
+        end
+      end
+
+      # Extract operations using OperationExtractor from the method's AST node.
+      #
+      # @param method_node [Ast::Node, nil]
+      # @return [Array<Hash>]
+      def extract_operations(method_node)
+        return [] unless method_node
+
+        @operation_extractor.extract(method_node)
+      rescue StandardError
+        []
+      end
+
+      # Return an empty side-effects structure.
+      #
+      # @return [Hash]
+      def empty_side_effects
+        {
+          columns_written: [],
+          jobs_enqueued: [],
+          services_called: [],
+          mailers_triggered: [],
+          database_reads: [],
+          operations: []
+        }
+      end
+    end
+  end
+end