woods 1.0.0

data/lib/woods/extractors/action_cable_extractor.rb

@@ -0,0 +1,201 @@
+# frozen_string_literal: true
+
+require_relative 'shared_utility_methods'
+require_relative 'shared_dependency_scanner'
+
+module Woods
+  module Extractors
+    # ActionCableExtractor handles ActionCable channel extraction via runtime introspection.
+    #
+    # Reads `ActionCable::Channel::Base.descendants` to discover channels, then inspects
+    # each channel's stream subscriptions, actions, broadcast patterns, and source code.
+    # Each channel becomes one ExtractedUnit with metadata about streams, actions, and
+    # broadcast patterns.
+    #
+    # @example
+    #   extractor = ActionCableExtractor.new
+    #   units = extractor.extract_all
+    #   chat = units.find { |u| u.identifier == "ChatChannel" }
+    #   chat.metadata[:stream_names]  #=> ["chat_room_#{params[:room_id]}"]
+    #   chat.metadata[:actions]       #=> ["speak", "typing"]
+    #
+    class ActionCableExtractor
+      include SharedUtilityMethods
+      include SharedDependencyScanner
+
+      # Lifecycle methods that are not user-defined actions
+      LIFECYCLE_METHODS = %i[subscribed unsubscribed].freeze
+
+      def initialize
+        # No directories to scan — this is runtime introspection
+      end
+
+      # Extract all ActionCable channels as ExtractedUnits.
+      #
+      # @return [Array<ExtractedUnit>] List of channel units
+      def extract_all
+        return [] unless action_cable_available?
+
+        channels = channel_descendants
+        return [] if channels.empty?
+
+        channels.filter_map { |klass| extract_channel(klass) }
+      end
+
+      # Extract a single channel class into an ExtractedUnit.
+      #
+      # Public for incremental re-extraction via CLASS_BASED dispatch.
+      #
+      # @param klass [Class] A channel subclass
+      # @return [ExtractedUnit, nil]
+      def extract_channel(klass)
+        name = klass.name
+        file_path = source_file_for(klass, name)
+        source = read_source(file_path)
+        own_methods = klass.instance_methods(false)
+
+        unit = ExtractedUnit.new(
+          type: :action_cable_channel,
+          identifier: name,
+          file_path: file_path
+        )
+
+        unit.namespace = extract_namespace(name)
+        unit.source_code = source
+        unit.metadata = build_metadata(source, own_methods)
+        unit.dependencies = source.empty? ? [] : scan_common_dependencies(source)
+
+        unit
+      rescue StandardError => e
+        log_extraction_error(name, e)
+        nil
+      end
+
+      private
+
+      # Check if ActionCable::Channel::Base is defined.
+      #
+      # @return [Boolean]
+      def action_cable_available?
+        defined?(ActionCable::Channel::Base)
+      end
+
+      # Retrieve channel descendants, filtering out abstract bases and anonymous classes.
+      #
+      # @return [Array<Class>]
+      def channel_descendants
+        ActionCable::Channel::Base.descendants.reject do |klass|
+          klass.name.nil? || klass.name == 'ApplicationCable::Channel'
+        end
+      end
+
+      # Locate the source file for a channel class.
+      #
+      # Convention path first, then introspection via {#resolve_source_location}
+      # which filters out vendor/node_modules paths.
+      #
+      # @param klass [Class] The channel class
+      # @param name [String] The channel class name
+      # @return [String, nil]
+      def source_file_for(klass, name)
+        return nil unless defined?(Rails) && Rails.respond_to?(:root) && Rails.root
+
+        convention_path = Rails.root.join('app', 'channels', "#{name.underscore}.rb").to_s
+        return convention_path if File.exist?(convention_path)
+
+        resolve_source_location(klass, app_root: Rails.root.to_s, fallback: nil)
+      end
+
+      # Read source code from a file path.
+      #
+      # @param file_path [String, nil]
+      # @return [String]
+      def read_source(file_path)
+        return '' unless file_path && File.exist?(file_path)
+
+        File.read(file_path)
+      rescue StandardError
+        ''
+      end
+
+      # Build metadata hash for a channel.
+      #
+      # @param source [String] Channel source code
+      # @param own_methods [Array<Symbol>] Methods defined directly on the channel
+      # @return [Hash]
+      def build_metadata(source, own_methods)
+        {
+          stream_names: detect_stream_names(source),
+          actions: detect_actions(own_methods),
+          has_subscribed: own_methods.include?(:subscribed),
+          has_unsubscribed: own_methods.include?(:unsubscribed),
+          broadcasts_to: detect_broadcasts(source),
+          loc: count_loc(source)
+        }
+      end
+
+      # Detect stream names from stream_from and stream_for calls.
+      #
+      # @param source [String] Channel source code
+      # @return [Array<String>]
+      def detect_stream_names(source)
+        streams = []
+
+        # stream_from "string" or stream_from 'string' (also catches interpolated strings)
+        streams.concat(source.scan(/stream_from\s+["']([^"']+)["']/).flatten)
+
+        # stream_for model
+        streams.concat(source.scan(/stream_for\s+(\w+)/).map { |m| "stream_for:#{m[0]}" })
+
+        streams.uniq
+      end
+
+      # Detect action methods (public instance methods minus lifecycle methods).
+      #
+      # @param own_methods [Array<Symbol>] Methods defined directly on the channel
+      # @return [Array<String>]
+      def detect_actions(own_methods)
+        (own_methods - LIFECYCLE_METHODS).map(&:to_s)
+      end
+
+      # Detect broadcast patterns in source code.
+      #
+      # @param source [String] Channel source code
+      # @return [Array<String>]
+      def detect_broadcasts(source)
+        broadcasts = []
+
+        # ActionCable.server.broadcast("channel_name", ...)
+        broadcasts.concat(source.scan(/ActionCable\.server\.broadcast\(\s*["']([^"']+)["']/).flatten)
+
+        # SomeChannel.broadcast_to(target, ...)
+        broadcasts.concat(source.scan(/\w+\.broadcast_to\(\s*(\w+)/).map { |m| "broadcast_to:#{m[0]}" })
+
+        broadcasts.uniq
+      end
+
+      # Count non-blank, non-comment lines.
+      #
+      # @param source [String]
+      # @return [Integer]
+      def count_loc(source)
+        return 0 if source.empty?
+
+        source.each_line.count do |line|
+          stripped = line.strip
+          !stripped.empty? && !stripped.start_with?('#')
+        end
+      end
+
+      # Log a channel extraction error.
+      #
+      # @param name [String] Channel class name
+      # @param error [StandardError]
+      def log_extraction_error(name, error)
+        return unless defined?(Rails) && Rails.respond_to?(:logger) && Rails.logger
+
+        Rails.logger.error("Failed to extract channel #{name}: #{error.message}")
+      end
+    end
+  end
+end

data/lib/woods/extractors/ast_source_extraction.rb

@@ -0,0 +1,46 @@
+# frozen_string_literal: true
+
+require_relative '../ast/method_extractor'
+
+module Woods
+  module Extractors
+    # Shared extraction of individual method source code via the AST layer.
+    #
+    # Included by extractors that need to pull a single method's source from
+    # a class (e.g., ControllerExtractor, MailerExtractor).
+    #
+    # @example
+    #   class FooExtractor
+    #     include AstSourceExtraction
+    #
+    #     def build_chunk(klass, action)
+    #       source = extract_action_source(klass, action)
+    #       # ...
+    #     end
+    #   end
+    #
+    module AstSourceExtraction
+      private
+
+      # Extract the source code of a single action method using the AST layer.
+      #
+      # @param klass [Class] The class that defines the method
+      # @param action [String, Symbol] The method name to extract
+      # @return [String, nil] The method source, or nil if not extractable
+      def extract_action_source(klass, action)
+        method = klass.instance_method(action)
+        source_location = method.source_location
+        return nil unless source_location
+
+        file, _line = source_location
+        return nil unless File.exist?(file)
+
+        source = File.read(file)
+        Ast::MethodExtractor.new.extract_method_source(source, action.to_s)
+      rescue StandardError => e
+        Rails.logger.debug("Could not extract action source for #{klass}##{action}: #{e.message}")
+        nil
+      end
+    end
+  end
+end

data/lib/woods/extractors/behavioral_profile.rb

@@ -0,0 +1,309 @@
+# frozen_string_literal: true
+
+module Woods
+  module Extractors
+    # BehavioralProfile introspects resolved Rails.application.config values
+    # to produce a single ExtractedUnit summarizing the app's runtime
+    # behavioral configuration.
+    #
+    # Sections extracted (each independently guarded):
+    # - Database: adapter, schema_format, belongs_to_required, has_many_inversing
+    # - Frameworks: ActionCable, ActiveStorage, ActionMailbox, ActionText, Turbo, Stimulus, SolidQueue, SolidCache
+    # - Behavior flags: api_only, eager_load, time_zone, strong params action, session store, filter params
+    # - Background processing: active_job queue_adapter
+    # - Caching: cache_store type
+    # - Email: delivery_method
+    #
+    # @example
+    #   profile = BehavioralProfile.new
+    #   unit = profile.extract
+    #   unit.metadata[:database][:adapter] #=> "postgresql"
+    #
+    class BehavioralProfile
+      # Frameworks to detect via `defined?` checks
+      FRAMEWORK_CHECKS = {
+        action_cable: 'ActionCable',
+        active_storage: 'ActiveStorage',
+        action_mailbox: 'ActionMailbox',
+        action_text: 'ActionText',
+        turbo: 'Turbo',
+        stimulus_reflex: 'StimulusReflex',
+        solid_queue: 'SolidQueue',
+        solid_cache: 'SolidCache'
+      }.freeze
+
+      # Extract a behavioral profile from the current Rails application.
+      #
+      # @return [ExtractedUnit, nil] A single configuration unit, or nil on catastrophic failure
+      def extract
+        config = Rails.application.config
+
+        profile = {
+          config_type: 'behavioral_profile',
+          rails_version: Rails.version,
+          ruby_version: RUBY_VERSION,
+          database: extract_database(config),
+          frameworks_active: extract_frameworks,
+          behavior_flags: extract_behavior_flags(config),
+          background_processing: extract_background(config),
+          caching: extract_caching(config),
+          email: extract_email(config)
+        }
+
+        build_unit(profile)
+      rescue StandardError => e
+        Rails.logger.error("BehavioralProfile extraction failed: #{e.message}")
+        nil
+      end
+
+      private
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Database
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Extract database configuration from ActiveRecord.
+      #
+      # @param config [Rails::Application::Configuration]
+      # @return [Hash]
+      def extract_database(config)
+        return {} unless defined?(ActiveRecord::Base)
+
+        result = {}
+
+        if ActiveRecord::Base.respond_to?(:connection_db_config)
+          result[:adapter] = ActiveRecord::Base.connection_db_config.adapter
+        end
+
+        if config.respond_to?(:active_record)
+          ar = config.active_record
+          result[:schema_format] = ar.schema_format if ar.respond_to?(:schema_format)
+          if ar.respond_to?(:belongs_to_required_by_default)
+            result[:belongs_to_required_by_default] = ar.belongs_to_required_by_default
+          end
+          result[:has_many_inversing] = ar.has_many_inversing if ar.respond_to?(:has_many_inversing)
+        end
+
+        result
+      rescue StandardError => e
+        Rails.logger.error("BehavioralProfile database section failed: #{e.message}")
+        {}
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Frameworks
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Detect which optional frameworks are loaded.
+      #
+      # @return [Hash]
+      def extract_frameworks
+        FRAMEWORK_CHECKS.transform_values do |constant_name|
+          Object.const_defined?(constant_name)
+        end
+      rescue StandardError => e
+        Rails.logger.error("BehavioralProfile frameworks section failed: #{e.message}")
+        {}
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Behavior flags
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Extract behavior flags from Rails config.
+      #
+      # @param config [Rails::Application::Configuration]
+      # @return [Hash]
+      def extract_behavior_flags(config)
+        flags = {}
+
+        safe_read(config, :api_only) { |v| flags[:api_only] = v }
+        safe_read(config, :eager_load) { |v| flags[:eager_load] = v }
+        safe_read(config, :time_zone) { |v| flags[:time_zone] = v }
+        safe_read(config, :session_store) { |v| flags[:session_store] = v }
+        safe_read(config, :filter_parameters) { |v| flags[:filter_parameters] = v }
+
+        if config.respond_to?(:action_controller)
+          ac = config.action_controller
+          if ac.respond_to?(:action_on_unpermitted_parameters)
+            flags[:action_on_unpermitted_parameters] = ac.action_on_unpermitted_parameters
+          end
+        end
+
+        flags
+      rescue StandardError => e
+        Rails.logger.error("BehavioralProfile behavior_flags section failed: #{e.message}")
+        {}
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Background processing
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Extract background processing configuration.
+      #
+      # @param config [Rails::Application::Configuration]
+      # @return [Hash]
+      def extract_background(config)
+        return {} unless config.respond_to?(:active_job)
+
+        aj = config.active_job
+        return {} unless aj.respond_to?(:queue_adapter)
+
+        { adapter: aj.queue_adapter }
+      rescue StandardError => e
+        Rails.logger.error("BehavioralProfile background section failed: #{e.message}")
+        {}
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Caching
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Extract caching configuration.
+      #
+      # @param config [Rails::Application::Configuration]
+      # @return [Hash]
+      def extract_caching(config)
+        return {} unless config.respond_to?(:cache_store)
+
+        raw = config.cache_store
+        store = raw.is_a?(Array) ? raw.first : raw
+
+        { store: store }
+      rescue StandardError => e
+        Rails.logger.error("BehavioralProfile caching section failed: #{e.message}")
+        {}
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Email
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Extract email delivery configuration.
+      #
+      # @param config [Rails::Application::Configuration]
+      # @return [Hash]
+      def extract_email(config)
+        return {} unless config.respond_to?(:action_mailer)
+
+        am = config.action_mailer
+        return {} unless am.respond_to?(:delivery_method)
+
+        { delivery_method: am.delivery_method }
+      rescue StandardError => e
+        Rails.logger.error("BehavioralProfile email section failed: #{e.message}")
+        {}
+      end
+
+      # ──────────────────────────────────────────────────────────────────────
+      # Unit construction
+      # ──────────────────────────────────────────────────────────────────────
+
+      # Build the ExtractedUnit from the assembled profile hash.
+      #
+      # @param profile [Hash]
+      # @return [ExtractedUnit]
+      def build_unit(profile)
+        unit = ExtractedUnit.new(
+          type: :configuration,
+          identifier: 'BehavioralProfile',
+          file_path: Rails.root.join('config/application.rb').to_s
+        )
+
+        unit.namespace = 'behavioral_profile'
+        unit.metadata = profile
+        unit.source_code = build_narrative(profile)
+        unit.dependencies = build_dependencies(profile)
+
+        unit
+      end
+
+      # Generate a human-readable narrative summary.
+      #
+      # @param profile [Hash]
+      # @return [String]
+      def build_narrative(profile)
+        lines = []
+        lines << '# Behavioral Profile'
+        lines << "# Rails #{profile[:rails_version]} / Ruby #{profile[:ruby_version]}"
+        lines << '#'
+
+        # Database
+        db = profile[:database]
+        if db.any?
+          lines << "# Database: #{db[:adapter] || 'unknown'}"
+          lines << "#   schema_format: #{db[:schema_format]}" if db[:schema_format]
+          unless db[:belongs_to_required_by_default].nil?
+            lines << "#   belongs_to_required: #{db[:belongs_to_required_by_default]}"
+          end
+          lines << "#   has_many_inversing: #{db[:has_many_inversing]}" unless db[:has_many_inversing].nil?
+        end
+
+        # Frameworks
+        active = profile[:frameworks_active].select { |_, v| v }
+        if active.any?
+          lines << '#'
+          lines << "# Active frameworks: #{active.keys.map { |k| FRAMEWORK_CHECKS[k] || k.to_s }.join(', ')}"
+        end
+
+        # Behavior flags
+        flags = profile[:behavior_flags]
+        if flags.any?
+          lines << '#'
+          lines << '# Behavior flags:'
+          flags.each { |k, v| lines << "#   #{k}: #{v}" }
+        end
+
+        # Background
+        bg = profile[:background_processing]
+        if bg.any?
+          lines << '#'
+          lines << "# Background: #{bg[:adapter]}"
+        end
+
+        # Caching
+        cache = profile[:caching]
+        if cache.any?
+          lines << '#'
+          lines << "# Cache store: #{cache[:store]}"
+        end
+
+        # Email
+        email = profile[:email]
+        if email.any?
+          lines << '#'
+          lines << "# Email delivery: #{email[:delivery_method]}"
+        end
+
+        lines.join("\n")
+      end
+
+      # Build dependency list from detected frameworks and adapters.
+      #
+      # @param profile [Hash]
+      # @return [Array<Hash>]
+      def build_dependencies(profile)
+        deps = []
+
+        profile[:frameworks_active].each do |key, active|
+          next unless active
+
+          constant_name = FRAMEWORK_CHECKS[key] || key.to_s
+          deps << { type: :framework, target: constant_name, via: :behavioral_profile }
+        end
+
+        deps
+      end
+
+      # Safely read a config attribute if it responds to it.
+      #
+      # @param obj [Object]
+      # @param method [Symbol]
+      # @yield [value] Yields the value if available
+      def safe_read(obj, method)
+        yield obj.public_send(method) if obj.respond_to?(method)
+      end
+    end
+  end
+end