html2rss 0.28.0 → 0.29.1

data/lib/html2rss/auto_source/segmenter.rb

@@ -19,11 +19,10 @@ module Html2rss
       # @option opts [Integer] :use_top_selectors list strategy selector budget
       # @option opts [Scoring::LinkResolver, nil] :link_resolver page-scoped destination facts cache
       # @return [Array<Segment>]
-      # rubocop:disable Style/ArgumentsForwarding -- keep named opts for YARD @option
+      # rubocop:disable-next Style/ArgumentsForwarding -- keep named opts for YARD @option
       def self.call(document, base_url:, strategy:, **opts)
         new(document, base_url:, strategy:, **opts).call
       end
-      # rubocop:enable Style/ArgumentsForwarding
 
       # @param document [SST::Document]
       # @param base_url [String, Html2rss::Url]

data/lib/html2rss/auto_source.rb

@@ -1,6 +1,8 @@
 # frozen_string_literal: true
 
 require 'dry-validation'
+require 'json'
+require 'nokogiri'
 
 module Html2rss
   ##
@@ -20,6 +22,14 @@ module Html2rss
     # Default max articles to keep (also the short-circuit floor across scraper tiers).
     DEFAULT_LIMIT = 25
 
+    # Operational scraper failures quarantined within a tier; programmer errors propagate.
+    OPERATIONAL_ERRORS = [
+      Html2rss::Error,
+      ArgumentError,
+      ::JSON::ParserError,
+      ::Nokogiri::SyntaxError
+    ].freeze
+
     # Default auto-source configuration shipped for scraper and cleanup behavior.
     DEFAULT_CONFIG = {
       limit: DEFAULT_LIMIT,
@@ -138,7 +148,7 @@ module Html2rss
 
     attr_reader :url, :parsed_body, :body, :request_session, :captured_responses
 
-    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+    # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
     def extract_articles
       articles = []
       matched = false
@@ -183,7 +193,6 @@ module Html2rss
       @admission_drops = result.drop_tallies
       result.articles.first(article_limit)
     end
-    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
     def enough_articles?(articles)
       return false if articles.size < article_limit
@@ -211,15 +220,20 @@ module Html2rss
     end
 
     def run_scraper(instance)
-      instance.each.map do |item|
-        case item
-        when Article
-          item
-        when Hash
-          Article.new(**item, scraper: instance.class)
-        else
-          raise TypeError, "#{instance.class} yielded #{item.class}; expected Article or Hash"
-        end
+      instance.map { |item| article_from_scraper_item(item, instance) }
+    rescue *OPERATIONAL_ERRORS => error
+      Log.warn("#{self.class}: #{instance.class} quarantined #{error.class}: #{error.message}")
+      []
+    end
+
+    def article_from_scraper_item(item, instance)
+      case item
+      when Article
+        item
+      when Hash
+        Article.new(**item, scraper: instance.class)
+      else
+        raise TypeError, "#{instance.class} yielded #{item.class}; expected Article or Hash"
       end
     end
 

data/lib/html2rss/batch.rb

@@ -0,0 +1,169 @@
+# frozen_string_literal: true
+
+module Html2rss
+  ##
+  # Concurrency-bounded batch execution over enumerables with input order preservation
+  # and per-item error isolation.
+  module Batch
+    # Maximum permitted worker threads for batch operations.
+    MAX_CONCURRENCY = 10
+    # Default worker threads for batch operations.
+    DEFAULT_CONCURRENCY = 5
+
+    # Value object representing the outcome of a batch operation.
+    BatchResult = Data.define(:total, :successful, :results) do
+      ##
+      # @return [Hash{Symbol => Object}]
+      def to_h
+        { total:, successful:, results: }
+      end
+    end
+
+    class << self
+      ##
+      # Executes a block concurrently across items using a bounded worker pool.
+      # Results are returned in input order.
+      #
+      # @param items [Enumerable<Object>]
+      # @param concurrency [Integer] max parallel worker threads (1..10, default: 5)
+      # @yieldparam item [Object]
+      # @return [Array<Object>]
+      def map(items, concurrency: DEFAULT_CONCURRENCY, &)
+        list = Array(items)
+        return [] if list.empty?
+
+        worker_count = worker_pool_size(list.size, concurrency)
+        process_queue(list, worker_count, &)
+      end
+
+      ##
+      # Runs a batch operation that yields items and wraps the results in a {BatchResult}.
+      #
+      # @param items [Enumerable<Object>]
+      # @param concurrency [Integer] max parallel worker threads (1..10, default: 5)
+      # @yieldparam item [Object]
+      # @return [BatchResult]
+      def run(items, concurrency: DEFAULT_CONCURRENCY, &)
+        list = Array(items)
+        results = map(list, concurrency:, &)
+        successful = results.count { |entry| entry.is_a?(Hash) ? entry[:ok] : !entry.nil? }
+
+        BatchResult.new(total: list.size, successful:, results:)
+      end
+
+      ##
+      # Single-URL scrape wire extraction: auto_feed_result → JSON Feed items.
+      #
+      # @param url [String]
+      # @param strategy [Symbol, String]
+      # @param limit [Integer]
+      # @param items_selector [String, nil]
+      # @return [Hash{Symbol => Object}] +:strategy+, +:items+, +:channel_title+, +:admission_drops+
+      def scrape_wire(url:, strategy:, limit:, items_selector: nil) # rubocop:disable Metrics/MethodLength
+        plan = (strategy || :auto).to_sym
+        feed_args = { strategy: plan, limit: }
+        feed_args[:items_selector] = items_selector unless items_selector.nil?
+        feed_result = Html2rss.auto_feed_result(url, **feed_args)
+        feed = feed_result.to_json_feed
+        {
+          strategy: plan,
+          items: feed[:items] || [],
+          channel_title: feed[:title],
+          admission_drops: feed_result.status.admission_drops
+        }
+      end
+
+      ##
+      # Scrapes multiple URLs in parallel with per-URL error isolation.
+      #
+      # @param urls [Enumerable<String>] list of URLs to scrape
+      # @param strategy [Symbol, String] request strategy (+:auto+, +:faraday+, +:botasaurus+)
+      # @param limit [Integer] max articles to extract per URL
+      # @param concurrency [Integer] number of worker threads (default 5, max 10)
+      # @return [BatchResult]
+      def batch_scrape(urls:, strategy: :auto, limit: 10, concurrency: DEFAULT_CONCURRENCY)
+        run(urls, concurrency:) { |url| scrape_single_url(url:, strategy:, limit:) }
+      end
+
+      ##
+      # Inspects multiple URLs in parallel with per-URL error isolation.
+      #
+      # @param urls [Enumerable<String>] list of URLs to inspect
+      # @param strategy [Symbol, String] request strategy (+:auto+, +:faraday+, +:botasaurus+)
+      # @param concurrency [Integer] number of worker threads (default 5, max 10)
+      # @return [BatchResult]
+      def batch_inspect(urls:, strategy: :auto, concurrency: DEFAULT_CONCURRENCY)
+        reports = PageRecon::Diagnostics.batch(urls:, strategy:, concurrency:)
+        results = reports.map(&:to_wire_h)
+        successful = reports.count { |report| diagnostic_success?(report) }
+
+        BatchResult.new(total: results.size, successful:, results:)
+      end
+
+      ##
+      # Runs recon across multiple URLs in parallel with per-URL error isolation.
+      #
+      # @param urls [Enumerable<String>] list of URLs to recon
+      # @param strategy [Symbol, String] request strategy (+:auto+, +:faraday+, +:botasaurus+)
+      # @param concurrency [Integer] number of worker threads (default 5, max 10)
+      # @option options [String, nil] :cache_dir optional HTML cache directory
+      # @return [BatchResult]
+      def batch_recon(urls:, strategy: :auto, concurrency: DEFAULT_CONCURRENCY, **)
+        results = Recon.batch(urls, strategy: (strategy || :auto).to_sym, max_threads: concurrency, **)
+        successful = results.count { |r| r.status ? r.status < 400 : false }
+        BatchResult.new(total: results.size, successful:, results: results.map(&:to_h))
+      end
+
+      private
+
+      def diagnostic_success?(report)
+        status = report.to_wire_h[:status]
+        status ? status < 400 : false
+      end
+
+      def scrape_single_url(url:, strategy:, limit:)
+        wire = scrape_wire(url:, strategy:, limit:)
+        {
+          url: url.to_s, ok: true, items_count: wire[:items].size,
+          items: wire[:items], channel_title: wire[:channel_title]
+        }
+      rescue StandardError => error
+        { url: url.to_s, ok: false, error: error.message }
+      end
+
+      def worker_pool_size(item_count, requested_concurrency)
+        return 1 if item_count <= 1
+
+        [[1, requested_concurrency.to_i].max, item_count, MAX_CONCURRENCY].min
+      end
+
+      def process_queue(items, worker_count, &)
+        queue = build_work_queue(items)
+        results = Array.new(items.size)
+
+        threads = Array.new(worker_count) do
+          Thread.new { drain_queue(queue, results, &) } # rubocop:disable ThreadSafety/NewThread
+        end
+        threads.each(&:join)
+        results
+      end
+
+      def build_work_queue(items)
+        Queue.new.tap do |queue|
+          items.each_with_index { |item, index| queue << [item, index] }
+        end
+      end
+
+      def drain_queue(queue, results)
+        until queue.empty?
+          begin
+            item, index = queue.pop(true)
+          rescue ThreadError
+            break
+          end
+          results[index] = yield(item)
+        end
+      end
+    end
+  end
+end

data/lib/html2rss/capture/README.md

@@ -1,6 +1,10 @@
 # Capture
 
-`Html2rss.capture` (and CLI `html2rss capture`) analyzes a URL through the feed pipeline and produces a reusable config with **items selector + `enhance: true` only** — no title/url/description attribute-selector soup. At feed-build time, `enhance: true` fills missing article fields via `Html::ArticleExtractor` on each matched item.
+`Html2rss.capture` (and CLI `html2rss capture`) analyzes a URL through the feed pipeline and produces a reusable config with **items selector + `enhance: true` only** — no title/url/description attribute-selector soup. At feed-build time, `enhance: true` fills missing article fields via `Html::ArticleExtractor` on each **matched list-card item node**.
+
+## API
+
+`Html2rss.capture` / `Capture.build` return `Capture::CaptureResult` — use `#yaml` or `#config`, not a bare Hash.
 
 ## When to use it
 
@@ -9,8 +13,9 @@ Point `capture` at a listing URL when you want a first-draft YAML config instead
 ## Gem API
 
 ```ruby
-config = Html2rss.capture('https://example.com/articles')
+result = Html2rss.capture('https://example.com/articles')
 
+# result.config =>
 # {
 #   channel: { url: "...", title: "...", time_zone: "UTC" },
 #   selectors: {
@@ -18,11 +23,13 @@ config = Html2rss.capture('https://example.com/articles')
 #   }
 # }
 
-File.write('my-feed.yml', YAML.dump(Html2rss::HashUtil.deep_stringify_keys(config)))
-feed = Html2rss.feed(config)
+File.write('my-feed.yml', result.yaml)
+rss = Html2rss.apply(result.config)
 ```
 
-`Capture.build` returns a `CaptureResult` with quality meta (`has_selectors`, `segment_strategy`, `admission_drops`, `selected_strategy`). `Html2rss.capture` returns only the config hash.
+`Html2rss.capture` and `Capture.build` both return a `CaptureResult` with YAML (`#yaml`, includes the schema modeline) and quality meta (`has_selectors`, `segment_strategy`, `admission_drops`, `selected_strategy`, `native_feed`).
+
+**Wire vs internal:** user-facing **`Html2rss.apply`** ships RSS from a config Hash. Pipeline internals **`Html2rss.feed` / `feed_result`** stay unchanged — use `apply` in CLI/MCP/docs examples, not `feed`.
 
 ### Options
 
@@ -30,15 +37,17 @@ feed = Html2rss.feed(config)
 Html2rss.capture('https://spa-site.com', strategy: :botasaurus)
 Html2rss.capture('https://example.com', items_selector: '.article-card')
 Html2rss.capture('https://example.com', strategy: :local_file, local_file_path: './page.html')
+Html2rss.capture('https://example.com', max_redirects: 8, max_requests: 4)
 ```
 
-`strategy: :auto` uses the same AutoFallback chain as scrape (`faraday` → `botasaurus`). When AutoFallback selects a concrete strategy (or you pin one), Capture **stamps** `strategy:` into the emitted config so later `Html2rss.feed(config)` replays the same transport.
+`strategy: :auto` uses the same AutoFallback chain as scrape (`faraday` → `botasaurus`). When AutoFallback selects a concrete strategy (or you pin one), Capture **stamps** `strategy:` into the emitted config so later `Html2rss.apply(config)` replays the same transport.
 
 ## CLI
 
 ```bash
 html2rss capture https://example.com/articles
 html2rss capture https://example.com --strategy botasaurus
+html2rss capture https://example.com --max-redirects 8 --max-requests 4
 html2rss capture https://example.com/articles > my-feed.yml
 html2rss capture https://example.com --input ./page.html
 html2rss capture https://example.com --explain   # quality JSON on stderr; YAML on stdout

data/lib/html2rss/capture.rb

@@ -2,28 +2,73 @@
 
 module Html2rss
   ##
-  # Analyzes a URL and produces a durable feed config: items selector + +enhance: true+.
+  # Analyzes a URL and produces a durable feed config: items selector + metadata.
   #
   # Fetches via {FeedPipeline} (including AutoFallback for +:auto+), extracts articles,
-  # then derives a reusable items CSS selector from SST segments (list → cluster → semantic).
+  # derives reusable items CSS selectors from SST segments, and infers directory catalog metadata.
   #
   # {include:file:lib/html2rss/capture/README.md}
   class Capture # rubocop:disable Metrics/ClassLength -- segment strategies + CSS trim stay co-located
     LEADING_TRIM_TAGS = %w[html body].freeze
     private_constant :LEADING_TRIM_TAGS
 
+    # Packaged YAML language server modeline.
+    SCHEMA_MODELINE = '# yaml-language-server: $schema=https://raw.githubusercontent.com/html2rss/html2rss/refs/heads/master/schema/html2rss-config.schema.json'
+
     # Ordered Segmenter strategies tried until the items selector quality gate passes.
     SEGMENT_STRATEGIES = %i[list cluster semantic].freeze
 
     # Minimum matched segment/article pairs required to emit an items selector.
     MIN_SELECTOR_MATCHES = 2
 
+    # Admission drops at or above this sum default enhance to false (chrome-heavy listing).
+    CHROME_DROP_THRESHOLD = 3
+    private_constant :CHROME_DROP_THRESHOLD
+
     ##
     # Result of a capture operation (config plus quality meta).
     CaptureResult = Data.define(
-      :config, :articles_count, :channel_title, :has_selectors, :segment_strategy,
-      :admission_drops, :selected_strategy
-    )
+      :config, :yaml, :articles_count, :channel_title, :has_selectors, :segment_strategy,
+      :admission_drops, :selected_strategy, :inferred_topics, :native_feed, :suggested_channel_url
+    ) do
+      # rubocop:disable Metrics/ParameterLists
+      ##
+      # @param config [Hash]
+      # @param articles_count [Integer]
+      # @param channel_title [String]
+      # @param has_selectors [Boolean]
+      # @param segment_strategy [Symbol]
+      # @param yaml [String, nil]
+      # @param admission_drops [Hash]
+      # @param selected_strategy [Symbol, nil]
+      # @param inferred_topics [Array<String>]
+      # @param native_feed [String, nil]
+      # @param suggested_channel_url [String, nil]
+      def initialize(config:, articles_count:, channel_title:, has_selectors:, segment_strategy:, # rubocop:disable Metrics/MethodLength
+                     yaml: nil, admission_drops: {}, selected_strategy: nil, inferred_topics: [], native_feed: nil,
+                     suggested_channel_url: nil)
+        super(
+          config:,
+          yaml: yaml || "#{SCHEMA_MODELINE}\n#{Config.to_yaml(config)}",
+          articles_count:,
+          channel_title:,
+          has_selectors:,
+          segment_strategy:,
+          admission_drops:,
+          selected_strategy:,
+          inferred_topics:,
+          native_feed:,
+          suggested_channel_url:
+        )
+      end
+      # rubocop:enable Metrics/ParameterLists
+
+      ##
+      # @return [Boolean] whether first-party RSS was detected
+      def native_feed?
+        !native_feed.nil?
+      end
+    end
 
     class << self
       ##
@@ -32,6 +77,11 @@ module Html2rss
       # @param url [String] source page URL
       # @param strategy [Symbol] request strategy (+:auto+, +:faraday+, +:botasaurus+)
       # @option options [String, nil] :items_selector optional selector hint
+      # @option options [Array<String>, nil] :topics optional directory topics override
+      # @option options [String, nil] :title optional title override
+      # @option options [String, nil] :summary optional summary override
+      # @option options [Boolean] :force whether to ignore native feed detection
+      # @option options [Boolean, nil] :enhance whether to force enhance: true
       # @option options [Integer, nil] :max_redirects optional redirect limit override
       # @option options [Integer, nil] :max_requests optional request budget override
       # @option options [Integer, nil] :limit max articles to keep
@@ -45,16 +95,25 @@ module Html2rss
     ##
     # @param url [String] source page URL
     # @param strategy [Symbol] request strategy
-    # @param options [Hash] additional options
     # @option options [String, nil] :items_selector optional selector hint
+    # @option options [Array<String>, nil] :topics optional directory topics override
+    # @option options [String, nil] :title optional title override
+    # @option options [String, nil] :summary optional summary override
+    # @option options [Boolean] :force whether to ignore native feed detection
+    # @option options [Boolean, nil] :enhance whether to force enhance: true
     # @option options [Integer, nil] :max_redirects optional redirect limit override
     # @option options [Integer, nil] :max_requests optional request budget override
     # @option options [Integer, nil] :limit max articles to keep
     # @option options [String, nil] :local_file_path optional local HTML file path
-    def initialize(url, strategy: :auto, **options)
+    def initialize(url, strategy: :auto, **options) # rubocop:disable Metrics/MethodLength
       @url = url
       @strategy = strategy
       @items_selector_hint = options.delete(:items_selector)
+      @topics = options.delete(:topics)
+      @title = options.delete(:title)
+      @summary = options.delete(:summary)
+      @force = options.delete(:force) || false
+      @enhance_option = options.delete(:enhance)
       @max_redirects = options.delete(:max_redirects)
       @max_requests = options.delete(:max_requests)
       @limit = options.delete(:limit)
@@ -65,12 +124,17 @@ module Html2rss
     # Runs the capture pipeline.
     #
     # @return [CaptureResult]
-    def build # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- outcome + selector + result assembly
+    def build # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       outcome = FeedPipeline.new(raw_config).to_outcome
+      @admission_drops = outcome.admission_drops
       selectors, segment_strategy = derive_selectors(outcome.response, outcome.articles)
+      ch_title = @title || channel_title_from(outcome.response)
+      topics = @topics || infer_topics("#{@url} #{ch_title}")
+      native_feed = probe_native_feed(outcome.response) unless @force
 
       config = {
-        channel: build_channel(outcome.response),
+        directory: build_directory(ch_title, topics),
+        channel: build_channel(outcome.response, ch_title),
         selectors: selectors.empty? ? nil : selectors,
         **strategy_stamp(outcome),
         **local_file_request_overlay
@@ -78,17 +142,75 @@ module Html2rss
 
       CaptureResult.new(
         config:,
+        yaml: "#{SCHEMA_MODELINE}\n#{Config.to_yaml(config)}",
         articles_count: outcome.articles.size,
-        channel_title: channel_title_from(outcome.response),
+        channel_title: ch_title,
         has_selectors: !selectors.empty?,
         segment_strategy:,
         admission_drops: outcome.admission_drops,
-        selected_strategy: outcome.selected_strategy
+        selected_strategy: outcome.selected_strategy,
+        inferred_topics: topics,
+        native_feed:,
+        suggested_channel_url: suggested_channel_url(outcome)
       )
     end
 
     private
 
+    def build_directory(title, topics)
+      summary_text = @summary || "#{title} updates and announcements."
+      {
+        topics: topics.take(2),
+        title:,
+        summary: summary_text[0, 160]
+      }.compact
+    end
+
+    def probe_native_feed(response)
+      return nil unless response && @url
+
+      Syndication::Discovery.best_feed_url(
+        page_url: @url,
+        request_session: discovery_session,
+        parsed_body: (response.parsed_body if response.html_response?),
+        html: response.body
+      )&.to_s
+    rescue StandardError
+      nil
+    end
+
+    def discovery_session
+      config = Config.from_hash(raw_config)
+      resources = FeedPipeline::RuntimePolicy.resources_for(config)
+      strategy = FeedPipeline::StrategyPlan.concrete_for_diagnostic(@strategy)
+      RequestSession.build(
+        config:,
+        strategy:,
+        budget: resources.budget,
+        policy: resources.policy
+      )
+    end
+
+    def infer_topics(text) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/PerceivedComplexity, Metrics/AbcSize, Metrics/MethodLength
+      t = text.to_s.downcase
+      inferred = []
+      inferred << 'tech' if /tech|developer|software|cloud|api|compute|ai|data|model|hardware|cyber/.match?(t)
+      inferred << 'security' if /security|vulnerab|advis|threat|breach|cve|cert|patch/.match?(t)
+      inferred << 'science' if /science|space|astron|physics|bio|research|institut|discover|nature/.match?(t)
+      inferred << 'energy' if /energy|wind|solar|power|grid|renewab|oil|gas|hydro/.match?(t)
+      inferred << 'finance' if /financ|bank|invest|monetary|market|regulat|treasury|econom/.match?(t)
+      inferred << 'civic' if /govern|policy|council|parliament|court|treaty|public/.match?(t)
+      inferred << 'environment' if /climat|environ|planet|sustainab|carbon|ecolog|earth/.match?(t)
+      inferred << 'consumer' if /consum|recall|safety|rating|test|product/.match?(t)
+      inferred << 'travel' if /travel|touris|destination|trip|flight|hotel|transit|rail/.match?(t)
+      inferred << 'sports' if /sport|olympic|racing|football|soccer|tennis|game/.match?(t)
+      inferred << 'health' if /health|medic|pharma|hospital|disease|patient/.match?(t)
+      inferred << 'education' if /educat|universit|school|student|academi|learn/.match?(t)
+      inferred << 'transport' if /transport|traffic|automotive|vehicle|train|bus/.match?(t)
+      valid = inferred.select { |topic| Config::Validator::DIRECTORY_TOPICS.include?(topic) }
+      valid.empty? ? ['news'] : valid.first(2)
+    end
+
     def strategy_stamp(outcome)
       concrete = outcome.selected_strategy || concrete_request_strategy
       return {} if concrete.nil? || concrete == :auto
@@ -147,11 +269,12 @@ module Html2rss
     end
 
     def hint_selectors
-      [{ items: { selector: @items_selector_hint, enhance: true } }, :hint]
+      [{ items: { selector: @items_selector_hint, enhance: resolve_enhance } }, :hint]
     end
 
     def select_enhance_selectors(sst, articles) # rubocop:disable Metrics/MethodLength -- strategy loop + gate
       link_resolver = Scoring::LinkResolver.new(@url)
+      enhance = resolve_enhance
 
       SEGMENT_STRATEGIES.each do |strategy|
         segments = AutoSource::Segmenter.call(
@@ -161,7 +284,7 @@ module Html2rss
         items_sel = items_selector(matched)
         next unless items_sel && matched.size >= MIN_SELECTOR_MATCHES
 
-        return [{ items: { selector: items_sel, enhance: true } }, strategy]
+        return [{ items: { selector: items_sel, enhance: } }, strategy]
       end
 
       [{}, nil]
@@ -301,10 +424,10 @@ module Html2rss
       "/#{prefix.join('/')}"
     end
 
-    def build_channel(response)
+    def build_channel(response, title = nil)
       {
         url: @url,
-        title: channel_title_from(response),
+        title: title || channel_title_from(response),
         time_zone: 'UTC'
       }.compact
     end
@@ -314,5 +437,25 @@ module Html2rss
     rescue StandardError
       nil
     end
+
+    def resolve_enhance
+      return @enhance_option unless @enhance_option.nil?
+
+      drops = (@admission_drops || {}).values.sum
+      drops < CHROME_DROP_THRESHOLD
+    end
+
+    def suggested_channel_url(outcome)
+      entry = outcome.scrape_target.entry_url.to_s
+      effective = outcome.scrape_target.effective_url.to_s
+      return effective unless Url.from_absolute(entry).same_document?(Url.from_absolute(effective))
+
+      final = outcome.response.url.to_s
+      return final unless Url.from_absolute(@url).same_document?(Url.from_absolute(final))
+
+      nil
+    rescue ArgumentError
+      nil
+    end
   end
 end

data/lib/html2rss/channel.rb

@@ -155,7 +155,7 @@ module Html2rss
     # @param last_build_date [Time, String]
     # @param image [Html2rss::Url, String, nil]
     # @param author [String, nil]
-    # rubocop:disable Metrics/ParameterLists -- Data.define members are the channel contract
+    # rubocop:disable-next Metrics/ParameterLists -- Data.define members are the channel contract
     def initialize(title:, url:, description:, language:, ttl:, last_build_date:, image:, author:)
       super(
         title: freeze_string(title),
@@ -168,7 +168,6 @@ module Html2rss
         author: author && freeze_string(author)
       )
     end
-    # rubocop:enable Metrics/ParameterLists
 
     private
 

data/lib/html2rss/cli/probe_view.rb

@@ -0,0 +1,66 @@
+# frozen_string_literal: true
+
+module Html2rss
+  class CLI
+    ##
+    # Display-only probe facts for inspect and recon text cards.
+    ProbeView = Data.define(
+      :requested,
+      :final,
+      :status,
+      :surface,
+      :articles_count,
+      :verdict,
+      :native_feed,
+      :alternate_feeds,
+      :notes,
+      :strategy
+    ) do
+      class << self
+        ##
+        # @param data [Hash] inspect wire payload
+        # @return [ProbeView]
+        def from_wire(data) # rubocop:disable Metrics/MethodLength
+          new(
+            requested: wire_val(data, :requested_url),
+            final: wire_val(data, :final_url),
+            status: wire_val(data, :status),
+            surface: wire_val(data, :surface_category),
+            articles_count: wire_val(data, :articles_count),
+            verdict: nil,
+            native_feed: nil,
+            alternate_feeds: wire_val(data, :alternate_feeds) || [],
+            notes: [],
+            strategy: wire_val(data, :strategy)
+          )
+        end
+
+        ##
+        # @param result [Html2rss::Recon::Result]
+        # @return [ProbeView]
+        def from_recon(result) # rubocop:disable Metrics/MethodLength
+          new(
+            requested: result.requested_url.to_s,
+            final: result.final_url.to_s,
+            status: result.status,
+            surface: result.surface_category,
+            articles_count: result.articles_count,
+            verdict: result.verdict,
+            native_feed: result.native_feed&.to_s,
+            alternate_feeds: [],
+            notes: result.notes,
+            strategy: nil
+          )
+        end
+
+        ##
+        # @param data [Hash]
+        # @param key [Symbol]
+        # @return [Object, nil]
+        def wire_val(data, key)
+          data[key] || data[key.to_s]
+        end
+      end
+    end
+  end
+end