woods 1.0.0

data/lib/woods/extractors/decorator_extractor.rb

@@ -0,0 +1,253 @@
+# frozen_string_literal: true
+
+require_relative 'shared_utility_methods'
+require_relative 'shared_dependency_scanner'
+
+module Woods
+  module Extractors
+    # DecoratorExtractor handles decorator, presenter, and form object extraction.
+    #
+    # Scans conventional directories for view-layer wrapper objects:
+    # decorators (Draper-style or PORO), presenters, and form objects.
+    # Extracts the decorated model relationship, delegation chains, and
+    # whether the Draper gem is in use.
+    #
+    # @example
+    #   extractor = DecoratorExtractor.new
+    #   units = extractor.extract_all
+    #   user_dec = units.find { |u| u.identifier == "UserDecorator" }
+    #   user_dec.metadata[:decorated_model]  # => "User"
+    #   user_dec.metadata[:uses_draper]      # => true
+    #
+    class DecoratorExtractor
+      include SharedUtilityMethods
+      include SharedDependencyScanner
+
+      # Directories to scan for decorator-style objects
+      DECORATOR_DIRECTORIES = %w[
+        app/decorators
+        app/presenters
+        app/form_objects
+      ].freeze
+
+      # Maps directory segment to decorator_type symbol
+      DIRECTORY_TYPE_MAP = {
+        'decorators' => :decorator,
+        'presenters' => :presenter,
+        'form_objects' => :form_object
+      }.freeze
+
+      # Suffixes used to infer the decorated model name
+      DECORATOR_SUFFIXES = %w[Decorator Presenter Form].freeze
+
+      def initialize
+        @directories = DECORATOR_DIRECTORIES.map { |d| Rails.root.join(d) }
+                                            .select(&:directory?)
+      end
+
+      # Extract all decorator, presenter, and form object units.
+      #
+      # @return [Array<ExtractedUnit>] List of decorator units
+      def extract_all
+        @directories.flat_map do |dir|
+          Dir[dir.join('**/*.rb')].filter_map do |file|
+            extract_decorator_file(file)
+          end
+        end
+      end
+
+      # Extract a single decorator file.
+      #
+      # @param file_path [String] Absolute path to the Ruby file
+      # @return [ExtractedUnit, nil] The extracted unit or nil if not a decorator
+      def extract_decorator_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: :decorator,
+          identifier: class_name,
+          file_path: file_path
+        )
+
+        unit.namespace = extract_namespace(class_name)
+        unit.source_code = annotate_source(source, class_name, file_path)
+        unit.metadata = extract_metadata(source, class_name, file_path)
+        unit.dependencies = extract_dependencies(source, class_name)
+
+        unit
+      rescue StandardError => e
+        Rails.logger.error("Failed to extract decorator #{file_path}: #{e.message}")
+        nil
+      end
+
+      private
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Class Discovery
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Override SharedUtilityMethods#extract_class_name for decorator-specific
+      # namespace resolution. The shared version only matches `class Foo::Bar`
+      # (inline namespacing); this version also handles `module Admin / class
+      # UserDecorator` (block namespacing) by scanning for enclosing modules.
+      #
+      # @param file_path [String] Path to the file
+      # @param source [String] Ruby source code
+      # @return [String, nil] The class name or nil
+      def extract_class_name(file_path, source)
+        namespaces = source.scan(/^\s*module\s+([\w:]+)/).flatten
+        class_match = source.match(/^\s*class\s+([\w:]+)/)
+
+        if class_match
+          base_class = class_match[1]
+          if namespaces.any? && !base_class.include?('::')
+            "#{namespaces.join('::')}::#{base_class}"
+          else
+            base_class
+          end
+        else
+          relative = file_path.sub("#{Rails.root}/", '')
+          relative
+            .sub(%r{^app/(decorators|presenters|form_objects)/}, '')
+            .sub('.rb', '')
+            .camelize
+        end
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Source Annotation
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Prepend a summary annotation header to the source.
+      #
+      # @param source [String] Ruby source code
+      # @param class_name [String] The class name
+      # @param file_path [String] Path to the file
+      # @return [String] Annotated source
+      def annotate_source(source, class_name, file_path)
+        decorator_type = infer_decorator_type(file_path)
+        decorated_model = infer_decorated_model(class_name)
+
+        annotation = <<~ANNOTATION
+          # ╔═══════════════════════════════════════════════════════════════════════╗
+          # ║ Decorator: #{class_name.ljust(57)}║
+          # ║ Type: #{decorator_type.to_s.ljust(62)}║
+          # ║ Decorates: #{(decorated_model || 'unknown').ljust(57)}║
+          # ╚═══════════════════════════════════════════════════════════════════════╝
+
+        ANNOTATION
+
+        annotation + source
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Metadata Extraction
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Build the metadata hash for a decorator unit.
+      #
+      # @param source [String] Ruby source code
+      # @param class_name [String] The class name
+      # @param file_path [String] Path to the file
+      # @return [Hash] Decorator metadata
+      def extract_metadata(source, class_name, file_path)
+        {
+          decorator_type: infer_decorator_type(file_path),
+          decorated_model: infer_decorated_model(class_name),
+          uses_draper: draper?(source),
+          delegated_methods: extract_delegated_methods(source),
+          public_methods: extract_public_methods(source),
+          entry_points: detect_entry_points(source),
+          class_methods: extract_class_methods(source),
+          initialize_params: extract_initialize_params(source),
+          loc: source.lines.count { |l| l.strip.length.positive? && !l.strip.start_with?('#') }
+        }
+      end
+
+      # Infer the decorator_type symbol from the file path.
+      #
+      # @param file_path [String] Absolute path to the file
+      # @return [Symbol] :decorator, :presenter, or :form_object
+      def infer_decorator_type(file_path)
+        DIRECTORY_TYPE_MAP.each do |dir_segment, type|
+          return type if file_path.include?("/#{dir_segment}/")
+        end
+        :decorator
+      end
+
+      # Infer the decorated model name by stripping known suffixes.
+      #
+      # @param class_name [String] e.g. "UserDecorator", "ProductPresenter"
+      # @return [String, nil] e.g. "User", "Product", or nil if not inferable
+      def infer_decorated_model(class_name)
+        base = class_name.split('::').last
+        DECORATOR_SUFFIXES.each do |suffix|
+          return base.delete_suffix(suffix) if base.end_with?(suffix) && base.length > suffix.length
+        end
+        nil
+      end
+
+      # Detect whether the class uses the Draper gem.
+      #
+      # @param source [String] Ruby source code
+      # @return [Boolean]
+      def draper?(source)
+        source.match?(/Draper::Decorator/)
+      end
+
+      # Extract method names passed to `delegate` calls.
+      #
+      # @param source [String] Ruby source code
+      # @return [Array<String>] Delegated method names
+      def extract_delegated_methods(source)
+        methods = []
+        source.scan(/\bdelegate\s+(.*?)(?:,\s*to:|$)/m) do |match|
+          match[0].scan(/:(\w+)/).flatten.each { |m| methods << m }
+        end
+        methods.uniq
+      end
+
+      # Override SharedUtilityMethods#detect_entry_points with decorator-specific
+      # entry points (decorate, present, to_partial_path) instead of the generic
+      # service-oriented ones (perform, execute, run, process).
+      #
+      # @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 << 'decorate'   if source.match?(/def (self\.)?decorate\b/)
+        points << 'present'    if source.match?(/def (self\.)?present\b/)
+        points << 'to_partial_path' if source.match?(/def to_partial_path\b/)
+        points.empty? ? ['unknown'] : points
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Dependency Extraction
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Build the dependency array for a decorator unit.
+      #
+      # Links to the decorated model via :decoration and scans the source
+      # for common code references (models, services, jobs, mailers).
+      #
+      # @param source [String] Ruby source code
+      # @param class_name [String] The class name
+      # @return [Array<Hash>] Dependency hashes with :type, :target, :via
+      def extract_dependencies(source, class_name)
+        deps = []
+
+        decorated_model = infer_decorated_model(class_name)
+        deps << { type: :model, target: decorated_model, via: :decoration } if decorated_model
+
+        deps.concat(scan_common_dependencies(source))
+
+        deps.uniq { |d| [d[:type], d[:target]] }
+      end
+    end
+  end
+end

data/lib/woods/extractors/engine_extractor.rb

@@ -0,0 +1,223 @@
+# frozen_string_literal: true
+
+require_relative 'shared_utility_methods'
+
+module Woods
+  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,
+          engine_source: framework_engine?(engine) ? :framework : :application
+        }
+        unit.dependencies = build_engine_dependencies(controllers)
+
+        unit
+      rescue StandardError => e
+        Rails.logger.error("Failed to extract engine #{engine.name}: #{e.message}")
+        nil
+      end
+
+      # Check if an engine is a framework gem rather than an application engine.
+      #
+      # An engine is framework if it lives outside Rails.root, or inside
+      # Rails.root but under vendor/bundle or bundler/gems (common in Docker
+      # where Rails.root is /app and gems install to /app/vendor/bundle).
+      #
+      # @param engine [Class] A Rails::Engine subclass
+      # @return [Boolean]
+      def framework_engine?(engine)
+        root = engine.root.to_s
+
+        # Engine outside Rails.root is definitely framework
+        return true unless root.start_with?(Rails.root.to_s)
+
+        # Engine inside Rails.root but in vendor/bundler paths is framework
+        root.include?('/vendor/') || root.include?('/bundler/gems/')
+      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/woods/extractors/event_extractor.rb

@@ -0,0 +1,211 @@
+# frozen_string_literal: true
+
+require_relative 'shared_utility_methods'
+require_relative 'shared_dependency_scanner'
+
+module Woods
+  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