html2rss 0.28.0 → 0.29.1

data/lib/html2rss/request_service/response.rb

@@ -31,7 +31,7 @@ module Html2rss
       # @param status [Integer, nil] the HTTP status code when available
       # @param transport_meta [Hash] allowlisted upstream telemetry (frozen when present)
       # @param captured_responses [Array<Hash>] JSON XHR/fetch bodies captured during browser scrapes
-      # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists -- transport + capture fields stay co-located
+      # rubocop:disable-next Metrics/MethodLength, Metrics/ParameterLists -- transport + capture fields stay co-located
       def initialize(body:, url:, headers: {}, status: nil, transport_meta: EMPTY_TRANSPORT_META,
                      captured_responses: EMPTY_CAPTURED_RESPONSES)
         @body = body
@@ -50,7 +50,6 @@ module Html2rss
                                 captured_responses.freeze
                               end
       end
-      # rubocop:enable Metrics/MethodLength, Metrics/ParameterLists
 
       # @return [String] the raw body of the response
       attr_reader :body
@@ -160,12 +159,12 @@ module Html2rss
         return false if ct.empty? || ct.include?('html') || ct.include?('json')
 
         # Substring match against Content-Type (not Array#intersect? on a String).
-        FEED_CT_MARKERS.any? { |marker| ct.include?(marker) } # rubocop:disable Style/ArrayIntersect
+        FEED_CT_MARKERS.any? { |marker| ct.include?(marker) }
       end
 
       def feed_looking_body?
         snippet = body.to_s[0, 800].downcase
-        FEED_BODY_MARKERS.any? { |marker| snippet.include?(marker) } # rubocop:disable Style/ArrayIntersect
+        FEED_BODY_MARKERS.any? { |marker| snippet.include?(marker) }
       end
     end
   end

data/lib/html2rss/request_service/strategy.rb

@@ -111,7 +111,7 @@ module Html2rss
 
       # @param reason [String] timeout classification (budget_exhausted / transport)
       # @return [void]
-      # rubocop:disable Metrics/AbcSize -- structured timeout fields stay in one log line
+      # rubocop:disable-next Metrics/AbcSize -- structured timeout fields stay in one log line
       def log_timeout!(reason:)
         remaining = ctx.budget.remaining_timeout_seconds
         remaining_label = remaining.nil? ? 'untracked' : format('%.3f', remaining)
@@ -124,7 +124,6 @@ module Html2rss
         ]
         Log.info("#{self.class}: request timeout #{detail.join(' ')}")
       end
-      # rubocop:enable Metrics/AbcSize
 
       # @param error [StandardError]
       # @return [void]

data/lib/html2rss/request_service.rb

@@ -29,6 +29,8 @@ module Html2rss
     class CrossOriginFollowUpDenied < Html2rss::Error; end
     # Raised when a response exceeds configured size limits.
     class ResponseTooLarge < Html2rss::Error; end
+    # Raised when HTTP redirect limits are exceeded.
+    class RedirectLimitReached < Html2rss::Error; end
     # Raised when blocked content surfaces are detected.
     class BlockedSurfaceDetected < Html2rss::Error; end
 

data/lib/html2rss/request_session.rb

@@ -18,14 +18,13 @@ module Html2rss
       # @param scrape_url [String, nil] effective fetch URL when it differs from config channel URL
       # @param logger [Logger] logger used for operational warnings
       # @return [RequestSession] configured request session
-      # rubocop:disable Metrics/ParameterLists -- scrape_url override stays beside config
+      # rubocop:disable-next Metrics/ParameterLists -- scrape_url override stays beside config
       def build(config:, strategy:, budget:, policy:, scrape_url: nil, logger: Html2rss::Log)
         context = RequestService::Context.new(
           url: scrape_url || config.url, headers: config.headers, request: config.request, policy:, budget:
         )
         new(context:, strategy:, logger:)
       end
-      # rubocop:enable Metrics/ParameterLists
     end
 
     ##

data/lib/html2rss/scrape_target.rb

@@ -4,7 +4,7 @@ module Html2rss
   ##
   # Immutable entry vs effective scrape URLs for one pipeline run.
   #
-  # Replaces mutating {Config#scrape_url=} after {FeedResolution} rewrites the fetch URL.
+  # Replaces mutating +Config#scrape_url=+ after {FeedResolution} rewrites the fetch URL.
   ScrapeTarget = Data.define(:entry_url, :effective_url) do
     ##
     # @param config [Html2rss::Config]

data/lib/html2rss/selectors/post_processors/sanitize_html.rb

@@ -105,7 +105,7 @@ module Html2rss
         # @param html [String]
         # @param url [String, Html2rss::Url]
         # @return [String, nil]
-        # rubocop:disable ThreadSafety/ClassInstanceVariable
+        # rubocop:disable-next ThreadSafety/ClassInstanceVariable
         def self.get(html, url)
           return nil if String(html).empty?
 
@@ -117,12 +117,11 @@ module Html2rss
           context = Selectors::Context.new(config: { channel: { url: } }, options: {})
           @fragment_cache[key] = new(html, context).get
         end
-        # rubocop:enable ThreadSafety/ClassInstanceVariable
 
         ##
         # @param channel_url [String, Html2rss::Url]
         # @return [Hash] the memoized sanitize configuration
-        # rubocop:disable Metrics/MethodLength, ThreadSafety/ClassInstanceVariable
+        # rubocop:disable-next Metrics/MethodLength, ThreadSafety/ClassInstanceVariable
         def self.sanitize_config(channel_url)
           @sanitize_configs ||= {}
           @sanitize_configs[channel_url] ||= begin
@@ -143,7 +142,6 @@ module Html2rss
             config.freeze
           end
         end
-        # rubocop:enable Metrics/MethodLength, ThreadSafety/ClassInstanceVariable
 
         ##
         # @return [String, nil]

data/lib/html2rss/selectors/post_processors.rb

@@ -23,7 +23,6 @@ module Html2rss
       # The key is the name to use in the feed config.
       NAME_TO_CLASS = {
         gsub: Gsub,
-        html_to_markdown: HtmlToMarkdown,
         markdown_to_html: MarkdownToHtml,
         parse_time: ParseTime,
         parse_uri: ParseUri,

data/lib/html2rss/selectors.rb

@@ -95,13 +95,16 @@ module Html2rss
     # @return [Hash] Hash of attributes for the article.
     def extract_article(item, page_response = response)
       scope = item_scope_for(item, page_response.url)
-      @rss_item_attributes.each_with_object({}) do |selector_key, hash|
+      hash = @rss_item_attributes.each_with_object({}) do |selector_key, h|
         value = scope.select(selector_key)
         next if value.nil?
 
         article_key = SELECTOR_TO_ARTICLE_KEY.fetch(selector_key, selector_key)
-        hash[article_key] = article_key == :enclosures ? wrap_enclosure_value(value) : value
+        h[article_key] = article_key == :enclosures ? wrap_enclosure_value(value) : value
       end
+
+      hash[:url] ||= default_item_url(item, page_response.url) if anchor_element?(item)
+      hash
     end
 
     ##
@@ -112,7 +115,7 @@ module Html2rss
     # @param article_tag [Nokogiri::XML::Element] HTML element to extract additional info from.
     # @param base_url [String, Html2rss::Url] base URL for normalization during enhancement
     # @return [Hash] The enhanced article hash.
-    # rubocop:disable Metrics/MethodLength
+    # rubocop:disable-next Metrics/MethodLength
     def enhance_article_hash(article_hash, article_tag, base_url = @url)
       selected_anchor = Html2rss::Html::Navigator.main_anchor_for(article_tag)
       extracted = Html2rss::Html::ArticleExtractor.call(
@@ -130,7 +133,6 @@ module Html2rss
         hash[key] = value
       end
     end
-    # rubocop:enable Metrics/MethodLength
 
     ##
     # Selects the value for a given attribute from an HTML element.
@@ -157,13 +159,11 @@ module Html2rss
 
       raise InvalidSelectorName, "Attribute selector '#{name}' is reserved for items." if name == ITEMS_SELECTOR_KEY
 
-      selector_key, config = selector_config_for(name)
+      selector_key, config = selector_config_for(name, allow_nil: name == :url)
+      return default_item_url(scope.item, scope.base_url) if fallback_url_selector?(selector_key, config, scope.item)
+      raise InvalidSelectorName, "Selector for '#{selector_key}' is not defined." if config.nil?
 
-      if SPECIAL_ATTRIBUTES.member?(selector_key)
-        select_special(selector_key, scope:, config:)
-      else
-        select_regular(selector_key, scope:, config:)
-      end
+      dispatch_select(selector_key, scope:, config:)
     end
 
     private
@@ -317,5 +317,28 @@ module Html2rss
 
       { url:, type: config[:content_type] }
     end
+
+    def anchor_element?(item)
+      item.respond_to?(:name) && item.name.to_s.casecmp('a').zero?
+    end
+
+    def fallback_url_selector?(selector_key, config, item)
+      selector_key == :url && config.nil? && anchor_element?(item)
+    end
+
+    def dispatch_select(selector_key, scope:, config:)
+      if SPECIAL_ATTRIBUTES.member?(selector_key)
+        select_special(selector_key, scope:, config:)
+      else
+        select_regular(selector_key, scope:, config:)
+      end
+    end
+
+    def default_item_url(item, base_url)
+      href = item['href'].to_s.strip
+      return if href.empty?
+
+      Url.from_relative(href, base_url)
+    end
   end
 end

data/lib/html2rss/sst/attrs.rb

@@ -29,7 +29,7 @@ module Html2rss
         # @param type [String, nil]
         # @param raw [Hash{String => String}, nil]
         # @return [Attrs]
-        # rubocop:disable Metrics/MethodLength, Metrics/ParameterLists
+        # rubocop:disable-next Metrics/MethodLength, Metrics/ParameterLists
         def build(href: nil, src: nil, id: nil, class_names: nil, datetime: nil, itemprop: nil,
                   style: nil, srcset: nil, type: nil, raw: nil)
           new(
@@ -45,7 +45,6 @@ module Html2rss
             raw: normalize_raw(raw)
           )
         end
-        # rubocop:enable Metrics/MethodLength, Metrics/ParameterLists
 
         ##
         # @return [Attrs]

data/lib/html2rss/sst/normalizer.rb

@@ -8,6 +8,9 @@ module Html2rss
     # Sole Nokogiri consumer on the heuristic auto-source path. Builds an
     # immutable SST::Document with parent/depth/chrome indices.
     class Normalizer # rubocop:disable Metrics/ClassLength
+      # Raised when no SST nodes survive normalization for the chosen root.
+      class EmptyTree < ArgumentError; end
+
       # Hard ceiling for SST node allocations; beyond this we degrade.
       MAX_NODES = 5_000
 
@@ -50,6 +53,12 @@ module Html2rss
         )
       /xi
 
+      # Typed Attrs fields excluded from the leftover raw hash.
+      TYPED_ATTR_NAMES = %w[href src id class datetime itemprop style srcset type].to_set.freeze
+
+      # String form of Tags::IGNORED_CONTAINER_NAMES for chrome checks without to_sym.
+      IGNORED_CONTAINER_TAGS = Tags::IGNORED_CONTAINER_NAMES.to_set(&:to_s).freeze
+
       class << self
         ##
         # @param input [String, Nokogiri::HTML::Document, Nokogiri::XML::Node]
@@ -89,9 +98,9 @@ module Html2rss
       ##
       # @return [Document]
       def call
-        root_nk = @parsed_body.respond_to?(:root) ? (@parsed_body.at_css('html') || @parsed_body.root) : @parsed_body
+        root_nk = resolve_root_nk
         root = normalize_element(root_nk, parent: nil, depth: 0, path: '', chrome: false)
-        raise ArgumentError, 'SST Normalizer produced an empty tree' unless root
+        raise EmptyTree, 'SST Normalizer produced an empty tree' unless root
 
         index = Index.new(root:, parents: @parents, depths: @depths, ignored_chrome: @ignored_chrome)
         Document.build(root:, index:, degraded: @degraded, node_count: @node_count)
@@ -99,14 +108,45 @@ module Html2rss
 
       private
 
-      # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+      # @return [Nokogiri::XML::Node]
+      # rubocop:disable-next Metrics/MethodLength -- explicit root discovery fallback chain
+      def resolve_root_nk
+        parsed = @parsed_body
+
+        if parsed.respond_to?(:at_css)
+          html = parsed.at_css('html')
+          return html if html
+
+          body = parsed.at_css('body')
+          if body
+            Html2rss::Log.warn('sst.normalizer root fallback: body')
+            return body
+          end
+        end
+
+        if parsed.respond_to?(:element_children)
+          first = parsed.element_children.find { |child| element_root?(child) }
+          if first
+            Html2rss::Log.warn('sst.normalizer root fallback: first element child')
+            return first
+          end
+        end
+
+        Html2rss::Log.warn('sst.normalizer root fallback: self')
+        parsed
+      end
+
+      def element_root?(node)
+        node.element? && !STRIPPED_TAGS.include?(Html2rss::Html::Probe.tag(node))
+      end
+
+      # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
       def normalize_element(nk_node, parent:, depth:, path:, chrome:)
         return unless nk_node.respond_to?(:name)
-        return if nk_node.text? || nk_node.comment? || nk_node.cdata?
+        return unless nk_node.element?
 
-        tag = nk_node.name.to_s.downcase
+        tag = Html2rss::Html::Probe.tag(nk_node)
         return if STRIPPED_TAGS.include?(tag)
-        return if @degraded && !SEMANTIC_DEGRADE_TAGS.include?(tag)
 
         if @node_count >= MAX_NODES && !@degraded
           @degraded = true
@@ -119,9 +159,9 @@ module Html2rss
         tag_path = path.empty? ? "/#{tag}" : "#{path}/#{tag}"
         attrs = extract_attrs(nk_node)
         own_text = direct_text(nk_node)
-        chrome_here = chrome || Tags::IGNORED_CONTAINER_NAMES.include?(tag.to_sym)
+        chrome_here = chrome || IGNORED_CONTAINER_TAGS.include?(tag)
 
-        children = nk_node.children.filter_map do |child|
+        children = nk_node.element_children.filter_map do |child|
           normalize_element(child, parent: :pending, depth: depth + 1, path: tag_path, chrome: chrome_here)
         end.freeze
 
@@ -135,7 +175,6 @@ module Html2rss
 
         node
       end
-      # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
       def extract_attrs(nk_node) # rubocop:disable Metrics/MethodLength
         Attrs.build(
@@ -153,10 +192,9 @@ module Html2rss
       end
 
       def raw_attrs(nk_node)
-        typed = %w[href src id class datetime itemprop style srcset type].to_set
         nk_node.attribute_nodes.each_with_object({}) do |attr, raw|
           name = attr.name.to_s
-          next if typed.include?(name)
+          next if TYPED_ATTR_NAMES.include?(name)
           next unless name.match?(RAW_ATTR_KEEP)
 
           raw[name] = attr.value.to_s

data/lib/html2rss/status.rb

@@ -26,7 +26,7 @@ module Html2rss # rubocop:disable Metrics/ModuleLength -- Status Data.define + m
       # @param scrape_url [String, nil] effective scrape URL after resolution
       # @param entry_resolution [Html2rss::FeedResolution::Diag, Hash, nil] resolution diagnostics
       # @return [Html2rss::Status]
-      # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength -- Status kwargs stay co-located
+      # rubocop:disable-next Metrics/ParameterLists, Metrics/MethodLength -- Status kwargs stay co-located
       def build(articles:, dedup_dropped: 0, selected_strategy: nil, attempt_count: 0,
                 strategy_attempts: [], admission_drops: {}, scrape_target: nil,
                 entry_url: nil, scrape_url: nil, entry_resolution: nil)
@@ -44,7 +44,6 @@ module Html2rss # rubocop:disable Metrics/ModuleLength -- Status Data.define + m
           entry_resolution:
         )
       end
-      # rubocop:enable Metrics/ParameterLists, Metrics/MethodLength
 
       ##
       # @param klass [Class, #to_s] scraper class
@@ -65,7 +64,7 @@ module Html2rss # rubocop:disable Metrics/ModuleLength -- Status Data.define + m
     # @param entry_url [String, nil]
     # @param scrape_url [String, nil]
     # @param entry_resolution [Hash, nil]
-    # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength -- Status Data.define members
+    # rubocop:disable-next Metrics/ParameterLists, Metrics/MethodLength -- Status Data.define members
     def initialize(
       version:, scraper_tallies:, dedup_dropped:, selected_strategy: nil, attempt_count: 0,
       strategy_attempts: [], admission_drops: {}, entry_url: nil, scrape_url: nil, entry_resolution: nil
@@ -87,13 +86,12 @@ module Html2rss # rubocop:disable Metrics/ModuleLength -- Status Data.define + m
         entry_resolution: freeze_entry_resolution(entry_resolution)
       )
     end
-    # rubocop:enable Metrics/ParameterLists, Metrics/MethodLength
 
     ##
     # Observability hash for web (+scraper_status+). Omits empty/absent optional keys.
     #
     # @return [Hash{Symbol => Object}]
-    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- omit-empty optional keys stay explicit
+    # rubocop:disable-next Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- omit-empty optional keys stay explicit
     def to_h
       {
         version:,
@@ -108,7 +106,6 @@ module Html2rss # rubocop:disable Metrics/ModuleLength -- Status Data.define + m
         **(entry_resolution ? { entry_resolution: } : {})
       }
     end
-    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
     ##
     # Formats the RSS +generator+ string and JSON Feed +user_comment+.

data/lib/html2rss/syndication/README.md

@@ -4,12 +4,12 @@ Native RSS/Atom discovery and parse for auto-source promotion and direct feed UR
 
 ## Ownership
 
-| Concern | Owner |
-| --- | --- |
-| Head `rel=alternate` + common path probes + status-gated feedish | `Syndication::Discovery` |
-| RSS 2.0 / Atom → article hashes | `Syndication::Parser` |
-| Strict head-only link parse (no path guessing) | `Html::FeedLink` |
-| Response Content-Type / body feed sniff | `RequestService::Response#feed_response?` (sole sniff owner; Discovery only adds HTTP status gate) |
+| Concern                                                          | Owner                                                                                              |
+| ---------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- |
+| Head `rel=alternate` + common path probes + status-gated feedish | `Syndication::Discovery`                                                                           |
+| RSS 2.0 / Atom → article hashes                                  | `Syndication::Parser`                                                                              |
+| Strict head-only link parse (no path guessing)                   | `Html::FeedLink`                                                                                   |
+| Response Content-Type / body feed sniff                          | `RequestService::Response#feed_response?` (sole sniff owner; Discovery only adds HTTP status gate) |
 
 ## Non-goals
 

data/lib/html2rss/syndication/discovery.rb

@@ -28,14 +28,13 @@ module Html2rss
       # @param extra_paths [Array<String>] additional path guesses
       # @param max_probes [Integer, nil] max candidate GETs (nil = uncapped)
       # @return [Html2rss::Url, nil]
-      # rubocop:disable Metrics/ParameterLists -- discovery kwargs stay co-located
+      # rubocop:disable-next Metrics/ParameterLists -- discovery kwargs stay co-located
       def best_feed_url(page_url:, request_session:, parsed_body: nil, html: nil, extra_paths: [],
                         max_probes: nil)
         best_feed_response(
           page_url:, request_session:, parsed_body:, html:, extra_paths:, max_probes:
         )&.url
       end
-      # rubocop:enable Metrics/ParameterLists
 
       ##
       # Like {#best_feed_url} but returns the validated syndication response for parsing.
@@ -47,7 +46,7 @@ module Html2rss
       # @param extra_paths [Array<String>]
       # @param max_probes [Integer, nil] max candidate GETs (nil = uncapped)
       # @return [Html2rss::RequestService::Response, nil]
-      # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength -- discovery kwargs stay co-located
+      # rubocop:disable-next Metrics/ParameterLists, Metrics/MethodLength -- discovery kwargs stay co-located
       def best_feed_response(page_url:, request_session:, parsed_body: nil, html: nil, extra_paths: [],
                              max_probes: nil)
         page = Html2rss::Url.from_absolute(page_url)
@@ -64,7 +63,6 @@ module Html2rss
           Log.info("Syndication::Discovery: host=#{page.host} selected_feed_url=#{response.url}")
         end
       end
-      # rubocop:enable Metrics/ParameterLists, Metrics/MethodLength
 
       ##
       # Ordered candidate feed URLs (head alternates first, then path guesses).

data/lib/html2rss/test/enhance_audit.rb

@@ -0,0 +1,192 @@
+# frozen_string_literal: true
+
+module Html2rss
+  module Test
+    ##
+    # Probes list-card +enhance+ value on cached listing HTML.
+    # Sole owner of enhance_gains metrics and enhance-specific warn-only warnings.
+    module EnhanceAudit # rubocop:disable Metrics/ModuleLength -- probe + compare + heuristics stay co-located
+      module_function
+
+      TRACKED_KEYS = %i[title url description published_at categories author image id enclosures].freeze
+      CURATOR_KEYS = %i[title url description published_at].freeze
+      private_constant :TRACKED_KEYS, :CURATOR_KEYS
+
+      ##
+      # Aggregate enhance probe metrics for one configuration test.
+      EnhanceGains = Data.define(:items_probed, :keys_added, :descriptions_added, :no_op)
+
+      ##
+      # Probe output merged into {QualityReport}.
+      AuditSlice = Data.define(:enhance_gains, :warnings)
+
+      IMAGE_FILENAME = /\.(jpe?g|png|gif|webp|avif|svg)\z/i
+      private_constant :IMAGE_FILENAME
+
+      ##
+      # @param response [Html2rss::RequestService::Response]
+      # @param selectors [Hash{Symbol => Object}]
+      # @param time_zone [String]
+      # @return [AuditSlice, nil] nil when selectors are absent
+      def probe(response:, selectors:, time_zone:) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- per-item probe loop
+        return nil unless selectors&.dig(:items, :selector)
+
+        selector_engine = Selectors.new(response, selectors:, time_zone:)
+        gains = {
+          items_probed: 0,
+          keys_added: zero_keys_added.dup,
+          descriptions_added: 0,
+          no_op: true
+        }
+        warnings = []
+
+        response.parsed_body.css(selector_engine.items_selector).each do |item|
+          baseline = selector_engine.extract_article(item, response)
+          enhanced = selector_engine.enhance_article_hash(baseline.dup, item, response.url)
+          item_keys = keys_added(baseline, enhanced)
+          merge_keys_added!(gains, item_keys)
+          append_item_warnings!(warnings, item:, enhanced:, item_keys:)
+        end
+
+        finalize_gains!(gains)
+        warnings << :enhance_no_op if gains.fetch(:no_op)
+        AuditSlice.new(
+          enhance_gains: EnhanceGains.new(
+            items_probed: gains.fetch(:items_probed),
+            keys_added: gains.fetch(:keys_added).freeze,
+            descriptions_added: gains.fetch(:descriptions_added),
+            no_op: gains.fetch(:no_op)
+          ),
+          warnings: warnings.freeze
+        )
+      end
+
+      ##
+      # @param response [Html2rss::RequestService::Response]
+      # @param selectors [Hash{Symbol => Object}]
+      # @param time_zone [String]
+      # @return [Hash{Symbol => Object}, nil]
+      def compare(response:, selectors:, time_zone:) # rubocop:disable Metrics/MethodLength -- enhance off/on stats + delta
+        return nil unless selectors&.dig(:items, :selector)
+
+        off = extraction_stats(response, selectors, time_zone, enhance: false)
+        on = extraction_stats(response, selectors, time_zone, enhance: true)
+        delta_gains = probe(response:, selectors:, time_zone:)&.enhance_gains || empty_gains
+
+        {
+          enhance_off: off,
+          enhance_on: on,
+          delta: {
+            descriptions_gained: on[:descriptions_filled] - off[:descriptions_filled],
+            keys_added: delta_gains.keys_added,
+            no_op: delta_gains.no_op
+          }
+        }
+      end
+
+      ##
+      # @return [EnhanceGains] zeroed gains for compare fallback
+      def empty_gains
+        EnhanceGains.new(
+          items_probed: 0,
+          keys_added: zero_keys_added,
+          descriptions_added: 0,
+          no_op: true
+        )
+      end
+
+      def zero_keys_added
+        TRACKED_KEYS.to_h { |key| [key, 0] }.freeze
+      end
+      private_class_method :zero_keys_added
+
+      def extraction_stats(response, selectors, time_zone, enhance:)
+        merged = selectors_with_enhance(selectors, enhance:)
+        articles = Selectors.new(response, selectors: merged, time_zone:).articles
+        {
+          item_count: articles.size,
+          descriptions_filled: articles.count { |article| article.description.to_s.strip != '' }
+        }
+      end
+      private_class_method :extraction_stats
+
+      def selectors_with_enhance(selectors, enhance:)
+        merged = HashUtil.deep_dup(selectors)
+        merged[:items] = merged.fetch(:items, {}).merge(enhance:)
+        merged
+      end
+      private_class_method :selectors_with_enhance
+
+      def keys_added(baseline, enhanced)
+        enhanced.each_with_object({}) do |(key, value), counts|
+          next if value.nil?
+
+          baseline_value = baseline[key]
+          next if baseline.key?(key) && baseline_value
+
+          counts[key] = (counts[key] || 0) + 1
+        end
+      end
+      private_class_method :keys_added
+
+      def merge_keys_added!(gains, item_keys)
+        gains[:items_probed] += 1
+        item_keys.each do |key, count|
+          next unless TRACKED_KEYS.include?(key)
+
+          gains[:keys_added][key] += count
+        end
+        gains[:descriptions_added] += item_keys.fetch(:description, 0)
+      end
+      private_class_method :merge_keys_added!
+
+      def finalize_gains!(gains)
+        curator_total = CURATOR_KEYS.sum { |key| gains[:keys_added][key] }
+        gains[:no_op] = curator_total.zero?
+      end
+      private_class_method :finalize_gains!
+
+      def append_item_warnings!(warnings, item:, enhanced:, item_keys:)
+        curator_added = item_keys.slice(*CURATOR_KEYS)
+        return if curator_added.empty?
+        return unless curator_added.key?(:description)
+
+        description = enhanced[:description].to_s.strip
+        return if description.empty?
+
+        if category_only_description?(description, enhanced)
+          warnings << :enhance_category_only_description
+        elsif image_only_description?(description, item)
+          warnings << :enhance_image_only_description
+        end
+      end
+      private_class_method :append_item_warnings!
+
+      def category_only_description?(description, enhanced)
+        normalized = description.downcase
+        return true if Html2rss::Html::ArticleRules::Description::TYPE_CHIPS.include?(normalized)
+
+        categories = Array(enhanced[:categories]).map { |category| category.to_s.strip }
+        categories.any? { |category| category.casecmp?(description) }
+      end
+      private_class_method :category_only_description?
+
+      def image_only_description?(description, item)
+        images = item.css('img')
+        return description == images.first['alt'].to_s.strip if images.size == 1 && images.first['alt']
+
+        prose_shaped?(description) == false
+      end
+      private_class_method :image_only_description?
+
+      def prose_shaped?(text)
+        return false if text.match?(IMAGE_FILENAME)
+        return false if text.match?(%r{\Ahttps?://}i)
+        return false if text.match?(%r{\A/[\w./-]+\z})
+
+        text.match?(/[a-z]/i)
+      end
+      private_class_method :prose_shaped?
+    end
+  end
+end