woods 1.0.0

data/lib/woods/extractors/lib_extractor.rb

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

@@ -0,0 +1,269 @@
+# frozen_string_literal: true
+
+require 'digest'
+require_relative 'ast_source_extraction'
+require_relative 'shared_utility_methods'
+require_relative 'shared_dependency_scanner'
+
+module Woods
+  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
+
+      # Locate the source file for a mailer class.
+      #
+      # Convention path first, then introspection via {#resolve_source_location}
+      # which filters out vendor/node_modules paths.
+      #
+      # @param mailer [Class]
+      # @return [String]
+      def source_file_for(mailer)
+        convention_path = Rails.root.join("app/mailers/#{mailer.name.underscore}.rb").to_s
+        return convention_path if File.exist?(convention_path)
+
+        resolve_source_location(mailer, app_root: Rails.root.to_s, fallback: convention_path)
+      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)
+        mailer_defaults = mailer.default
+        mailer_defaults.slice(:from, :reply_to, :cc, :bcc).compact
+      rescue StandardError
+        {}
+      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
+
+      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

data/lib/woods/extractors/manager_extractor.rb

@@ -0,0 +1,188 @@
+# frozen_string_literal: true
+
+require_relative 'shared_utility_methods'
+require_relative 'shared_dependency_scanner'
+
+module Woods
+  module Extractors
+    # ManagerExtractor handles SimpleDelegator subclass extraction.
+    #
+    # Manager/delegator objects wrap a model and provide a richer interface
+    # for specific contexts (e.g., OrderManager wrapping Order with
+    # checkout-specific methods). They live in `app/managers/`.
+    #
+    # We extract:
+    # - Wrapped model (via SimpleDelegator superclass or initializer)
+    # - Public methods (the manager's added interface)
+    # - Delegation chain (what gets delegated vs overridden)
+    # - Dependencies (what models/services they reference)
+    #
+    # @example
+    #   extractor = ManagerExtractor.new
+    #   units = extractor.extract_all
+    #   order_mgr = units.find { |u| u.identifier == "OrderManager" }
+    #
+    class ManagerExtractor
+      include SharedUtilityMethods
+      include SharedDependencyScanner
+
+      # Directories to scan for manager/delegator objects
+      MANAGER_DIRECTORIES = %w[
+        app/managers
+      ].freeze
+
+      def initialize
+        @directories = MANAGER_DIRECTORIES.map { |d| Rails.root.join(d) }
+                                          .select(&:directory?)
+      end
+
+      # Extract all manager/delegator objects
+      #
+      # @return [Array<ExtractedUnit>] List of manager units
+      def extract_all
+        @directories.flat_map do |dir|
+          Dir[dir.join('**/*.rb')].filter_map do |file|
+            extract_manager_file(file)
+          end
+        end
+      end
+
+      # Extract a single manager file
+      #
+      # @param file_path [String] Path to the manager file
+      # @return [ExtractedUnit, nil] The extracted unit or nil if not a manager
+      def extract_manager_file(file_path)
+        source = File.read(file_path)
+        class_name = extract_class_name(file_path, source, 'managers')
+
+        return nil unless class_name
+        return nil unless manager_file?(source)
+
+        unit = ExtractedUnit.new(
+          type: :manager,
+          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, class_name)
+
+        unit
+      rescue StandardError => e
+        Rails.logger.error("Failed to extract manager #{file_path}: #{e.message}")
+        nil
+      end
+
+      private
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Class Discovery
+      # ──────────────────────────────────────────────────────────────────────
+
+      def manager_file?(source)
+        source.match?(/< SimpleDelegator/) ||
+          source.match?(/< DelegateClass\(/) ||
+          source.match?(/include Delegator/)
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Source Annotation
+      # ──────────────────────────────────────────────────────────────────────
+
+      def annotate_source(source, class_name)
+        wrapped = detect_wrapped_model(source, class_name)
+
+        <<~ANNOTATION
+          # ╔═══════════════════════════════════════════════════════════════════════╗
+          # ║ Manager: #{class_name.ljust(60)}║
+          # ║ Wraps: #{(wrapped || 'unknown').ljust(61)}║
+          # ╚═══════════════════════════════════════════════════════════════════════╝
+
+          #{source}
+        ANNOTATION
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Metadata Extraction
+      # ──────────────────────────────────────────────────────────────────────
+
+      def extract_metadata(source, class_name)
+        {
+          wrapped_model: detect_wrapped_model(source, class_name),
+          delegation_type: detect_delegation_type(source),
+          public_methods: extract_public_methods(source),
+          class_methods: extract_class_methods(source),
+          initialize_params: extract_initialize_params(source),
+          delegated_methods: extract_delegated_methods(source),
+          overridden_methods: extract_overridden_methods(source),
+          custom_errors: extract_custom_errors(source),
+          loc: source.lines.count { |l| l.strip.length.positive? && !l.strip.start_with?('#') },
+          method_count: source.scan(/def\s+(?:self\.)?\w+/).size
+        }
+      end
+
+      def detect_wrapped_model(source, class_name)
+        # DelegateClass(ModelName) pattern
+        return ::Regexp.last_match(1) if source =~ /< DelegateClass\((\w+)\)/
+
+        # super(model) in initialize
+        return ::Regexp.last_match(1).capitalize if source =~ /super\((\w+)\)/
+
+        # @model = model; super(model) — look for param name
+        if source =~ /def\s+initialize\s*\((\w+)/
+          param = ::Regexp.last_match(1)
+          return param.capitalize unless %w[args options params attributes].include?(param)
+        end
+
+        # Infer from class name: OrderManager -> Order
+        stripped = class_name.split('::').last
+        inferred = stripped.sub(/Manager\z/, '')
+        # Return nil if no suffix was removed (not a FooManager pattern)
+        return nil if inferred == stripped || inferred.empty?
+
+        inferred
+      end
+
+      def detect_delegation_type(source)
+        return :delegate_class if source.match?(/< DelegateClass\(/)
+        return :simple_delegator if source.match?(/< SimpleDelegator/)
+
+        :unknown
+      end
+
+      def extract_delegated_methods(source)
+        methods = []
+
+        # delegate :foo, :bar, to: :something
+        source.scan(/delegate\s+(.+?)(?:,\s*to:)/) do |match|
+          match[0].scan(/:(\w+)/).flatten.each { |m| methods << m }
+        end
+
+        methods
+      end
+
+      def extract_overridden_methods(source)
+        # Methods that call super — these override delegated behavior
+        source.scan(/def\s+(\w+[?!=]?).*?\n.*?super/m).flatten
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Dependency Extraction
+      # ──────────────────────────────────────────────────────────────────────
+
+      def extract_dependencies(source, class_name)
+        deps = []
+
+        # Wrapped model dependency (specific :via)
+        wrapped = detect_wrapped_model(source, class_name)
+        deps << { type: :model, target: wrapped, via: :delegation } if wrapped
+
+        deps.concat(scan_common_dependencies(source))
+
+        deps.uniq { |d| [d[:type], d[:target]] }
+      end
+    end
+  end
+end