html2rss 0.25.0 → 0.27.0

data/lib/html2rss/config/selectors_validator.rb

@@ -75,6 +75,9 @@ module Html2rss
       ##
       # Validates the configuration of a single selector.
       class Selector < Dry::Validation::Contract
+        # Extractor Options members supplied at runtime, not from feed YAML.
+        RUNTIME_EXTRACTOR_FIELDS = %i[selector channel].to_set.freeze
+
         params do
           optional(:selector)
           optional(:extractor).filled(:string)
@@ -88,33 +91,69 @@ module Html2rss
         end
 
         rule(:extractor) do
-          # dependent on the extractor, validate required fields, (i.e. static, attribute)
-          case value
-          when 'attribute'
-            key(:attribute).failure('`attribute` must be a string') unless values[:attribute].is_a?(String)
-          when 'static'
-            key(:static).failure('`static` must be a string') unless values[:static].is_a?(String)
+          next unless value
+
+          klass = Selectors::Extractors::NAME_TO_CLASS[value.to_sym]
+          next key(:extractor).failure("unknown extractor: #{value}") unless klass
+
+          klass::Options.members.each do |field|
+            next if RUNTIME_EXTRACTOR_FIELDS.include?(field)
+            next if values[field]
+
+            key(field).failure("`#{field}` is required for extractor `#{value}`")
           end
         end
 
         rule(:post_process).each do
-          case (name = value[:name])
-          when 'gsub'
-            key(:pattern).failure('`pattern` must be a string') unless value[:pattern].is_a?(String)
-            key(:replacement).failure('`replacement` must be a string') unless value[:replacement].is_a?(String)
-          when 'substring'
-            key(:start).failure('`start` must be an integer') unless value[:start].is_a?(Integer)
-            key(:end).failure('`end` must be an integer or omitted') if !value[:end].nil? && !value[:end].is_a?(Integer)
-          when 'template'
-            key(:string).failure('`string` must be a string') unless value[:string].is_a?(String)
-          when 'html_to_markdown', 'markdown_to_html', 'parse_time', 'parse_uri', 'sanitize_html'
-            # nothing to validate
-          when nil
-            key(:post_process).failure('Missing post_processor `name`')
-          else
-            key(:post_process).failure("Unknown post_processor `name`: #{name}")
+          name = value[:name]
+          next key(:post_process).failure('Missing post_processor `name`') if name.nil?
+
+          klass = Selectors::PostProcessors::NAME_TO_CLASS[name.to_sym]
+          next key(:post_process).failure("Unknown post_processor `name`: #{name}") unless klass
+          next unless klass.const_defined?(:Options)
+
+          post_process_option_type_errors(klass, value).each do |field, message|
+            key(field).failure(message)
           end
         end
+
+        private
+
+        def post_process_option_type_errors(klass, value)
+          required_option_type_errors(klass, value) + optional_option_type_errors(klass, value)
+        end
+
+        def required_option_type_errors(klass, value)
+          option_types = klass.const_defined?(:OPTION_TYPES) ? klass::OPTION_TYPES : {}
+
+          klass::Options.members.filter_map do |field|
+            expected = option_types.fetch(field, String)
+            next if value[field].is_a?(expected)
+
+            [field, option_type_failure(field, expected)]
+          end
+        end
+
+        def optional_option_type_errors(klass, value)
+          return [] unless klass.const_defined?(:OPTIONAL_OPTION_TYPES)
+
+          klass::OPTIONAL_OPTION_TYPES.filter_map do |field, expected|
+            actual = value[field]
+            next if actual.nil? || actual.is_a?(expected)
+
+            [field, option_type_failure(field, expected, optional: true)]
+          end
+        end
+
+        def option_type_failure(field, expected, optional: false)
+          label = {
+            Integer => 'an integer',
+            String => 'a string',
+            Hash => 'a hash'
+          }.fetch(expected) { "a #{expected}" }
+          suffix = optional ? ' or omitted' : ''
+          "`#{field}` must be #{label}#{suffix}"
+        end
       end
 
       ##

data/lib/html2rss/config/validator.rb

@@ -15,6 +15,11 @@ module Html2rss
       LANGUAGE_FORMAT_REGEX = /\A[a-z]{2}(-[A-Z]{2})?\z/
       # Baseline strategy-plan enum (:auto plus concrete RequestService strategies).
       BASE_STRATEGY_OPTIONS = Html2rss::FeedPipeline::StrategyPlan.accepted_names.freeze
+      # Controlled vocabulary for catalog-only `directory.topics` (not RSS channel fields).
+      DIRECTORY_TOPICS = %w[
+        sports energy tech science news entertainment jobs finance
+        security travel environment consumer civic product research
+      ].freeze
 
       # Contract for the top-level `channel` section.
       ChannelConfig = Dry::Schema.Params do
@@ -28,6 +33,11 @@ module Html2rss
         optional(:image).maybe(:string, format?: URI_REGEXP)
       end
 
+      # Contract for catalog-only `directory` metadata (topics for feed directories).
+      DirectoryConfig = Dry::Schema.Params do
+        optional(:topics).value(:array, min_size?: 1).each(:string, included_in?: DIRECTORY_TOPICS)
+      end
+
       # Contract for a stylesheet entry in `stylesheets`.
       StylesheetConfig = Dry::Schema.Params do
         required(:href).filled(:string)
@@ -35,47 +45,40 @@ module Html2rss
         optional(:media).maybe(:string)
       end
 
-      # Contract for Browserless click-preload options.
-      BrowserlessPreloadClickSelectorConfig = Dry::Schema.Params do
-        required(:selector).filled(:string)
-        optional(:max_clicks).filled(:integer, gt?: 0)
-        optional(:wait_after_ms).filled(:integer, gteq?: 0)
-      end
-
-      # Contract for Browserless scroll-preload options.
-      BrowserlessPreloadScrollConfig = Dry::Schema.Params do
-        optional(:iterations).filled(:integer, gt?: 0)
-        optional(:wait_after_ms).filled(:integer, gteq?: 0)
-      end
-
-      # Contract for Browserless preload orchestration options.
-      BrowserlessPreloadConfig = Dry::Schema.Params do
-        optional(:wait_after_ms).filled(:integer, gteq?: 0)
-        optional(:click_selectors).array(BrowserlessPreloadClickSelectorConfig)
-        optional(:scroll_down).hash(BrowserlessPreloadScrollConfig)
-      end
-
-      # Contract for Browserless-specific request options.
-      BrowserlessRequestConfig = Dry::Schema.Params do
-        optional(:preload).hash(BrowserlessPreloadConfig)
-      end
-
-      # Contract for Botasaurus-specific request options.
+      # Contract for Botasaurus-specific request options (OpenAPI ScrapeRequest minus url).
       BotasaurusRequestConfig = Dry::Schema.Params do
         config.validate_keys = true
 
-        optional(:navigation_mode).filled(:string, included_in?: %w[auto get google_get google_get_bypass])
-        optional(:max_retries).filled(:integer, gteq?: 0, lteq?: 3)
+        botasaurus = Html2rss::RequestService::BotasaurusContract
+
+        optional(:execution_mode).filled(:string, included_in?: botasaurus::EXECUTION_MODES)
+        optional(:navigation_mode).filled(:string, included_in?: botasaurus::NAVIGATION_MODES)
+        optional(:max_retries).filled(:integer, gteq?: 0, lteq?: botasaurus::MAX_RETRIES)
         optional(:wait_for_selector).maybe(:string)
-        optional(:wait_timeout_seconds).filled(:integer, gt?: 0)
+        optional(:wait_timeout_seconds).filled(
+          :integer, gteq?: botasaurus::MIN_WAIT_TIMEOUT_SECONDS, lteq?: botasaurus::MAX_WAIT_TIMEOUT_SECONDS
+        )
+        optional(:scroll).filled(:bool)
         optional(:block_images).filled(:bool)
         optional(:block_images_and_css).filled(:bool)
+        optional(:block_trackers).filled(:bool)
         optional(:wait_for_complete_page_load).filled(:bool)
         optional(:headless).filled(:bool)
         optional(:proxy).filled(:string)
         optional(:user_agent).filled(:string)
-        optional(:window_size).value(:array, min_size?: 2, max_size?: 2).each(:integer, gt?: 0)
+        optional(:window_size).hash do
+          botasaurus::WINDOW_SIZE_PROPERTIES.each do |key|
+            required(key).filled(:integer, gt?: 0)
+          end
+        end
         optional(:lang).filled(:string)
+        optional(:cookies).hash
+        optional(:headers).hash
+      end
+
+      # JSON Schema export adapter for +BotasaurusRequestConfig+ (params schemas have no json_schema).
+      class BotasaurusRequestExport < Dry::Validation::Contract
+        params(BotasaurusRequestConfig)
       end
 
       # Contract for the top-level `request` section.
@@ -83,14 +86,14 @@ module Html2rss
         optional(:max_redirects).filled(:integer, gteq?: 0)
         optional(:max_requests).filled(:integer, gt?: 0)
         optional(:total_timeout_seconds).filled(:integer, gt?: 0)
-        optional(:browserless).hash(BrowserlessRequestConfig)
-        optional(:botasaurus).hash(BotasaurusRequestConfig)
+        optional(:botasaurus).hash
         optional(:local_file_path).filled(:string)
       end
 
       params do
         optional(:strategy).filled(:symbol)
         required(:channel).hash(ChannelConfig)
+        optional(:directory).hash(DirectoryConfig)
         optional(:headers).hash
         optional(:stylesheets).array(StylesheetConfig)
         optional(:auto_source).hash(Config::AutoSourceContract)
@@ -132,6 +135,17 @@ module Html2rss
         errors.each { |error| key(:selectors).failure(error.text) } unless errors.empty?
       end
 
+      rule(request: :botasaurus) do
+        next unless value
+
+        result = BotasaurusRequestConfig.call(value)
+        next if result.success?
+
+        result.errors.each do |error|
+          key([:request, :botasaurus, *error.path]).failure(error.text)
+        end
+      end
+
       # URL validation delegated to Url class
       rule(:channel) do
         if (url_string = values.dig(:channel, :url)) && !url_string.empty?

data/lib/html2rss/config.rb

@@ -71,6 +71,34 @@ module Html2rss
         validate(load_yaml(file, feed_name, multiple_feeds_key:), params:)
       end
 
+      ##
+      # Serializes a configuration hash to string-key YAML.
+      #
+      # This is the single serializer for CLI capture and MCP +capture_config+.
+      #
+      # @param hash [Hash] configuration hash (symbol or string keys)
+      # @return [String] YAML document without Ruby symbol-key prefixes
+      def to_yaml(hash)
+        YAML.dump(HashUtil.deep_stringify_keys(hash))
+      end
+
+      ##
+      # Parses a YAML configuration string into a symbol-keyed hash.
+      #
+      # Does not validate. Call {validate} or {from_hash} after this.
+      #
+      # @param string [String] YAML document
+      # @return [Hash{Symbol => Object}] configuration hash
+      # @raise [ArgumentError] if +string+ is not a String or does not deserialize to a Hash
+      def from_yaml(string)
+        raise ArgumentError, 'YAML must be a String' unless string.is_a?(String)
+
+        parsed = YAML.safe_load(string)
+        raise ArgumentError, 'YAML must deserialize to a Hash' unless parsed.is_a?(Hash)
+
+        HashUtil.deep_symbolize_keys(parsed, context: 'config')
+      end
+
       ##
       # Loads the feed configuration from a YAML file.
       #

data/lib/html2rss/error.rb

@@ -6,19 +6,31 @@ module Html2rss
 
   # Raised when auto fallback exhausts all concrete tiers and extractors find no feed items.
   class NoFeedItemsExtracted < Error
+    # Categories that append shared surface guidance to the empty-feed message.
+    SURFACE_HINT_CATEGORIES = %i[app_shell blocked_surface high_entropy_surface].freeze
+
     ##
     # @param attempts [Array<Hash{Symbol => Object}>] tier attempt diagnostics
-    def initialize(attempts:)
+    # @param surface_category [Symbol, nil] optional Scraper surface classification
+    def initialize(attempts:, surface_category: nil)
       @attempts = attempts
+      @surface_category = surface_category
       super(build_message)
     end
 
     # @return [Array<Hash{Symbol => Object}>] tier attempt diagnostics
     attr_reader :attempts
 
+    # @return [Symbol, nil] surface classification when a response body was available
+    attr_reader :surface_category
+
     private
 
     def build_message
+      [base_message, surface_guidance, botasaurus_guidance].compact.join(' ')
+    end
+
+    def base_message
       summaries = attempts.map do |attempt|
         details = attempt[:items_count].nil? ? "#{attempt[:error_class]} error" : "#{attempt[:items_count]} items"
         "#{attempt[:strategy]} (#{details})"
@@ -27,5 +39,23 @@ module Html2rss
       "No feed items extracted after auto fallback across strategies: #{summaries}. " \
         'Try a more specific listing URL or provide explicit selectors.'
     end
+
+    def surface_guidance
+      return unless SURFACE_HINT_CATEGORIES.include?(surface_category)
+
+      AutoSource::Scraper::NoScraperFound::CATEGORY_MESSAGES.fetch(surface_category)
+    end
+
+    def botasaurus_guidance
+      return unless botasaurus_configuration_error_attempt?
+      return if surface_guidance&.include?('BOTASAURUS_SCRAPER_URL')
+
+      RequestService::BotasaurusConfigurationError::EMPTY_FEED_HINT
+    end
+
+    def botasaurus_configuration_error_attempt?
+      error_name = RequestService::BotasaurusConfigurationError.name
+      attempts.any? { |attempt| attempt[:error_class] == error_name }
+    end
   end
 end

data/lib/html2rss/feed_pipeline/README.md

@@ -0,0 +1,42 @@
+# FeedPipeline — `auto` request strategy
+
+`:auto` is the default request plan for feed builds (`auto_source`, `auto_json_feed`, Capture, and MCP `scrape_url` / `capture_config`). `FeedPipeline::StrategyPlan` resolves it; `FeedPipeline::AutoFallback` executes `AutoFallback::CHAIN`.
+
+Use `:auto` when you want Faraday first and a browser-backed hop only if that fetch fails or yields zero items. Pin a concrete strategy (`faraday`, `botasaurus`, `local_file`) when you need a single transport.
+
+## Chain
+
+`AutoFallback::CHAIN` is:
+
+1. **Faraday** — plain HTTP (faster, cheaper).
+2. **Botasaurus** — attempted when Faraday raises a fallback-eligible error (for example `BlockedSurfaceDetected` or timeout) or extracts zero feed items.
+
+There is no Browserless / Puppeteer-in-gem tier. Pin `botasaurus` when you want browser rendering without Faraday first. Botasaurus needs `BOTASAURUS_SCRAPER_URL`.
+
+## Surfaces
+
+| Surface | `:auto` behavior |
+|---------|------------------|
+| Gem / CLI feed build, MCP `scrape_url`, Capture | Full AutoFallback chain (`faraday` → `botasaurus`) |
+| MCP `inspect_url` | Cheap diagnostic: `StrategyPlan.concrete_for_diagnostic` maps `auto` to Faraday (pin `botasaurus` when you need browser rendering) |
+
+## Fallback vs abort
+
+These typically hop to the next chain member (among other `StandardError`s `AutoFallback` rescues):
+
+- `Html2rss::RequestService::BlockedSurfaceDetected`
+- `Html2rss::RequestService::RequestTimedOut`
+- Faraday connection / timeout errors
+- Empty extraction results when a later chain member may succeed
+
+These abort immediately (`AutoFallback::NON_FALLBACK_ERRORS`): unknown strategy, invalid URL, unsupported scheme, budget exceeded, private network denied, cross-origin follow-up denied, response too large.
+
+Retries share the feed's request/session policy. Pin a concrete strategy when you need a single-hop budget profile.
+
+## Success signals
+
+- `Html2rss::RequestService::Response` includes transport metadata for the strategy that produced it.
+- `Html2rss::Status` records selected strategy and attempt tallies for MCP envelope payload / CLI `--explain`.
+- Fallback hops log at info/warn (`AutoFallback`).
+
+See also {Html2rss::AutoSource} for article scraping (a different pipeline) and {Html2rss::Capture} for durable configs that stamp the selected strategy.

data/lib/html2rss/feed_pipeline/auto_fallback.rb

@@ -6,7 +6,7 @@ module Html2rss
     #
     # Owned by {FeedPipeline}; invoked only after {StrategyPlan} resolves +:auto+.
     # Hosted by the pipeline instance: session + extract call back into FeedPipeline.
-    class AutoFallback
+    class AutoFallback # rubocop:disable Metrics/ClassLength -- attempt state + logging stay co-located
       # Ordered list of concrete request strategies attempted by the :auto plan.
       CHAIN = %i[faraday botasaurus].freeze
 
@@ -15,22 +15,21 @@ module Html2rss
         RequestService::UnknownStrategy,
         RequestService::InvalidUrl,
         RequestService::UnsupportedUrlScheme,
-        RequestService::UnsupportedResponseContentType,
         RequestService::RequestBudgetExceeded,
         RequestService::PrivateNetworkDenied,
         RequestService::CrossOriginFollowUpDenied,
-        RequestService::ResponseTooLarge,
-        RequestService::BrowserlessConfigurationError
+        RequestService::ResponseTooLarge
       ].freeze
 
       ##
       # Mutable run state for one auto-fallback chain: attempts plus selected result.
       class AttemptState
-        attr_reader :attempts, :result
+        attr_reader :attempts, :result, :last_response
 
         def initialize
           @attempts = []
           @result = nil
+          @last_response = nil
         end
 
         # @return [Boolean] true when a strategy already yielded items
@@ -53,22 +52,33 @@ module Html2rss
           @attempts << attempt
         end
 
+        # @param response [RequestService::Response] last response that reached extraction
+        # @return [void]
+        def remember_response(response)
+          @last_response = response
+        end
+
         # @param response [RequestService::Response] successful response
         # @param articles [Array] extracted articles
         # @param dedup_dropped [Integer] articles removed by deduplication
         # @param selected_strategy [Symbol] concrete strategy that produced items
         # @param attempt_count [Integer] number of attempts recorded for this chain
+        # @param admission_drops [Hash{String => Integer}] Cleanup drop tallies
         # @return [void]
-        def succeed!(response:, articles:, dedup_dropped:, selected_strategy:, attempt_count:)
+        # rubocop:disable Metrics/ParameterLists -- PipelineOutcome kwargs stay co-located
+        def succeed!(response:, articles:, dedup_dropped:, selected_strategy:, attempt_count:,
+                     admission_drops: {})
           @result = PipelineOutcome.new(
             response:,
             articles:,
             dedup_dropped:,
             selected_strategy:,
             attempt_count:,
-            strategy_attempts: attempts
+            strategy_attempts: attempts,
+            admission_drops:
           )
         end
+        # rubocop:enable Metrics/ParameterLists
       end
 
       ##
@@ -92,7 +102,7 @@ module Html2rss
         state = run_attempts
         return state.result if state.succeeded?
 
-        finalize_failure(attempts: state.attempts)
+        finalize_failure(attempts: state.attempts, response: state.last_response)
       end
 
       private
@@ -114,6 +124,9 @@ module Html2rss
         return unless response
 
         process_response(response:, strategy:, next_strategy:, request_session:, state:)
+      rescue RequestService::UnsupportedResponseContentType => error
+        state.record_error(strategy:, error:)
+        log_fallback_error(strategy:, next_strategy:, error:, request_session:) if next_strategy
       end
 
       def fetch_response(request_session:, strategy:, next_strategy:, state:)
@@ -126,14 +139,18 @@ module Html2rss
         nil
       end
 
-      def process_response(response:, strategy:, next_strategy:, request_session:, state:)
-        articles, dedup_dropped = articles_for(response:, request_session:)
+      def process_response(response:, strategy:, next_strategy:, request_session:, state:) # rubocop:disable Metrics/MethodLength -- extract + success path
+        articles, dedup_dropped, admission_drops = articles_for(response:, request_session:)
+        state.remember_response(response)
         items_count = articles.size
         state.record_items(strategy:, items_count:, transport_meta: response.transport_meta)
         Log.debug("#{self.class}: strategy=#{strategy} items=#{items_count} " \
                   "host=#{response.url.host} elapsed=#{format('%.3f', budget.elapsed_seconds)}s " \
                   "budget_remaining=#{budget_remaining_label}")
-        return record_success(response:, strategy:, articles:, dedup_dropped:, state:) if items_count.positive?
+        if items_count.positive?
+          return record_success(response:, strategy:, articles:, dedup_dropped:, admission_drops:,
+                                state:)
+        end
 
         log_info_fallback_zero_items(strategy:, next_strategy:, response:) if next_strategy
       end
@@ -142,18 +159,24 @@ module Html2rss
         pipeline.deduplicated_articles(config:, response:, request_session:)
       end
 
-      def record_success(response:, strategy:, articles:, dedup_dropped:, state:)
+      # rubocop:disable Metrics/ParameterLists -- success kwargs match PipelineOutcome
+      def record_success(response:, strategy:, articles:, dedup_dropped:, admission_drops:, state:)
         attempt_count = state.attempts.size
-        state.succeed!(response:, articles:, dedup_dropped:, selected_strategy: strategy, attempt_count:)
+        state.succeed!(response:, articles:, dedup_dropped:, selected_strategy: strategy,
+                       attempt_count:, admission_drops:)
         return unless attempt_count > 1
 
         Log.info("#{self.class}: auto selected strategy=#{strategy} after attempts=#{attempt_count} " \
                  "host=#{response.url.host} elapsed=#{format('%.3f', budget.elapsed_seconds)}s " \
                  "budget_remaining=#{budget_remaining_label}")
       end
+      # rubocop:enable Metrics/ParameterLists
 
-      def finalize_failure(attempts:)
-        raise NoFeedItemsExtracted.new(attempts:)
+      def finalize_failure(attempts:, response:)
+        surface_category = response && AutoSource::Scraper.classify_no_scraper_surface(
+          response.parsed_body, body: response.body
+        )
+        raise NoFeedItemsExtracted.new(attempts:, surface_category:)
       end
 
       # rubocop:disable Metrics/AbcSize, Metrics/MethodLength

data/lib/html2rss/feed_pipeline/runtime_policy.rb

@@ -6,8 +6,7 @@ module Html2rss
     # Planner for the runtime request policy and budgets of a feed run.
     #
     # HTTP request slots (pagination, document GETs, strategy fallback) are planned
-    # separately from Browserless preload interaction budget so preload cannot steal
-    # pagination slots.
+    # from configuration options.
     class RuntimePolicy
       # Policy plus Budget from one config expansion (shared meters for a feed run).
       Resources = Data.define(:policy, :budget)
@@ -34,26 +33,18 @@ module Html2rss
           policy:,
           budget: RequestService::Budget.new(
             max_requests: policy.max_requests,
-            max_interactions: interaction_budget_for(config),
             total_timeout_seconds: policy.total_timeout_seconds
           )
         )
       end
 
       ##
-      # Builds a Budget with separate request and interaction slot pools.
+      # Builds a Budget with request slot pools.
       #
       # @param config [Html2rss::Config] validated feed config
       # @return [Html2rss::RequestService::Budget] shared budget for the feed build
       def self.budget_for(config) = resources_for(config).budget
 
-      ##
-      # @param config [Html2rss::Config] validated feed config
-      # @return [Integer] preload interaction slots derived from browserless preload config
-      def self.interaction_budget_for(config)
-        browserless_preload_budget_for(config)
-      end
-
       class << self
         private
 
@@ -64,44 +55,13 @@ module Html2rss
         end
 
         # Reserve enough HTTP request slots for the initial request plus predictable
-        # follow-ups. Preload interactions are planned separately.
+        # follow-ups.
         def baseline_request_budget_for(config)
           1 +
             RequestSession::Pager.request_slots_for(config.selectors&.dig(:items, :pagination)) +
             AutoSource.request_slots_for(config.auto_source) +
             StrategyPlan.resolve(config.strategy).request_slots
         end
-
-        def browserless_preload_budget_for(config)
-          preload = config.request.dig(:browserless, :preload)
-          return 0 unless preload
-
-          top_level_preload_wait_budget(preload) +
-            click_selector_preload_budget(preload) +
-            scroll_preload_budget(preload)
-        end
-
-        def top_level_preload_wait_budget(preload)
-          preload[:wait_after_ms] ? 2 : 0
-        end
-
-        def click_selector_preload_budget(preload)
-          preload.fetch(:click_selectors, []).sum { preload_action_budget(_1, :max_clicks) }
-        end
-
-        def scroll_preload_budget(preload)
-          scroll = preload[:scroll_down]
-          return 0 unless scroll
-
-          preload_action_budget(scroll, :iterations)
-        end
-
-        def preload_action_budget(config, count_key)
-          action_count = config.fetch(count_key, 1)
-          wait_budget = config[:wait_after_ms] ? action_count : 0
-
-          action_count + wait_budget
-        end
       end
     end
   end

data/lib/html2rss/feed_pipeline/strategy_plan.rb

@@ -41,6 +41,17 @@ module Html2rss
           Concrete.new(strategy: normalized)
         end
 
+        ##
+        # Cheap single-request diagnostic default: +:auto+ → +:faraday+.
+        # Does not run {AutoFallback}. Prefer {resolve} for scrape/capture feeds.
+        #
+        # @param name [Symbol, String, nil] plan name (+nil+ → +:auto+)
+        # @return [Symbol] concrete {RequestService} strategy
+        def concrete_for_diagnostic(name = AUTO_NAME)
+          plan = resolve(name || AUTO_NAME)
+          plan.is_a?(Auto) ? RequestService.default_strategy_name : plan.strategy
+        end
+
         ##
         # @param name [Symbol, String, nil] candidate plan name
         # @return [Boolean] whether +name+ is a valid feed-level strategy plan