html2rss 0.32.4 → 0.34.0

data/lib/html2rss/request_service.rb

@@ -8,28 +8,67 @@ module Html2rss
   # Feed-level +:auto+ is not registered here — {FeedPipeline::StrategyPlan} resolves
   # it to a concrete strategy (or {FeedPipeline::AutoFallback} chain) before execute.
   class RequestService
+    extend ResponseCaching
+
     # Raised when an unknown request strategy is requested.
     class UnknownStrategy < Html2rss::Error; end
+
     # Raised when a URL cannot be parsed or validated.
-    class InvalidUrl < Html2rss::Error; end
+    class InvalidUrl < Html2rss::Error
+      # @return [Symbol]
+      def kind = :invalid_url
+    end
+
     # Raised when a URL uses an unsupported scheme.
-    class UnsupportedUrlScheme < Html2rss::Error; end
+    class UnsupportedUrlScheme < Html2rss::Error
+      # @return [Symbol]
+      def kind = :invalid_url
+    end
+
     # Raised when a response type cannot be parsed.
     class UnsupportedResponseContentType < Html2rss::Error; end
+
     # Raised when HTTP request slot limits are exceeded.
-    class RequestBudgetExceeded < Html2rss::Error; end
+    class RequestBudgetExceeded < Html2rss::Error
+      # @return [Symbol]
+      def kind = :budget
+    end
+
     # Raised when policy denies private-network access.
-    class PrivateNetworkDenied < Html2rss::Error; end
+    class PrivateNetworkDenied < Html2rss::Error
+      # @return [Symbol]
+      def kind = :blocked
+    end
+
     # Raised when cross-origin follow-up requests are denied.
-    class CrossOriginFollowUpDenied < Html2rss::Error; end
+    class CrossOriginFollowUpDenied < Html2rss::Error
+      # @return [Symbol]
+      def kind = :blocked
+    end
+
     # Raised when a response exceeds configured size limits.
-    class ResponseTooLarge < Html2rss::Error; end
+    class ResponseTooLarge < Html2rss::Error
+      # @return [Symbol]
+      def kind = :budget
+    end
+
     # Raised when HTTP redirect limits are exceeded.
-    class RedirectLimitReached < Html2rss::Error; end
+    class RedirectLimitReached < Html2rss::Error
+      # @return [Symbol]
+      def kind = :budget
+    end
+
     # Raised when blocked content surfaces are detected.
-    class BlockedSurfaceDetected < Html2rss::Error; end
+    class BlockedSurfaceDetected < Html2rss::Error
+      # @return [Symbol]
+      def kind = :blocked
+    end
+
     # Raised when the target connection fails before a response document exists.
-    class ConnectionFailed < Html2rss::Error; end
+    class ConnectionFailed < Html2rss::Error
+      # @return [Symbol]
+      def kind = :connection
+    end
 
     # Raised when a request times out.
     class RequestTimedOut < Html2rss::Error
@@ -43,6 +82,9 @@ module Html2rss
 
       # @return [String, nil] scrape-api timeout stage, or nil for transport/budget timeouts
       attr_reader :timeout_phase
+
+      # @return [Symbol]
+      def kind = :timeout
     end
 
     # Raised when Botasaurus configuration is missing or invalid.
@@ -52,7 +94,11 @@ module Html2rss
     end
 
     # Raised when the Botasaurus service cannot be reached (network / DNS / SSL).
-    class BotasaurusConnectionFailed < Html2rss::Error; end
+    class BotasaurusConnectionFailed < Html2rss::Error
+      # @return [Symbol]
+      def kind = :connection
+    end
+
     # Raised when Botasaurus responds but the scrape fails (upstream error, bad payload).
     class BotasaurusServiceError < Html2rss::Error; end
 
@@ -82,9 +128,22 @@ module Html2rss
     MAX_DEPRECATION_WARNINGS = 256
     # Mutex guarding process-local deprecation warning deduplication.
     DEPRECATION_MUTEX = Mutex.new
-    private_constant :DEPRECATION_MUTEX
+    # Mutex guarding the process-wide cookie store reference.
+    COOKIE_STORE_MUTEX = Mutex.new
+    private_constant :DEPRECATION_MUTEX, :COOKIE_STORE_MUTEX
 
     class << self
+      # @param store [#fetch, #write, #evict, nil] replacement cookie store (nil restores the in-memory default)
+      # @return [void]
+      def cookie_store=(store)
+        COOKIE_STORE_MUTEX.synchronize { @cookie_store = store }
+      end
+
+      # @return [#fetch, #write, #evict] the configured cookie store (in-memory by default)
+      def cookie_store
+        COOKIE_STORE_MUTEX.synchronize { @cookie_store ||= CookieStore.new }
+      end
+
       # @return [Symbol] the default strategy name
       def default_strategy_name = DEFAULT_STRATEGY_NAME
 
@@ -112,7 +171,7 @@ module Html2rss
                 "The strategy '#{strategy}' is not known. Available strategies: #{strategy_names.join(', ')}"
         end
 
-        strategy_class.new(ctx).execute
+        fetch_initial_through_cache(ctx, strategy_sym) { strategy_class.new(ctx).execute }
       end
 
       ##

data/lib/html2rss/request_session/pager/base.rb

@@ -26,7 +26,7 @@ module Html2rss
         # @yield [RequestService::Response] each page response
         # @return [Enumerator] enumerator when no block is given
         def each
-          return enum_for(:each) unless block_given?
+          return enum_for unless block_given?
 
           yield initial_response
 
@@ -48,14 +48,14 @@ module Html2rss
 
         # @return [Integer] configured maximum pages (always a positive Integer)
         def max_pages
-          value = config.fetch(:max_pages, DEFAULT_MAX_PAGES)
+          value = config[:max_pages]
           value.is_a?(Integer) && value.positive? ? value : DEFAULT_MAX_PAGES
         end
 
         # @param next_url [Html2rss::Url, String, nil]
         # @return [Boolean]
         def follow_up_allowed?(next_url)
-          !next_url.nil? && !next_url.to_s.empty? && !session.visited?(next_url)
+          !next_url.to_s.empty? && !session.visited?(next_url)
         end
 
         # @param next_url [Html2rss::Url, String]
@@ -70,13 +70,6 @@ module Html2rss
           )
           nil
         end
-
-        # @param page_response [RequestService::Response]
-        # @param page_number [Integer] 1-based target page number (e.g. 2 for second page)
-        # @return [Html2rss::Url, String, nil]
-        def next_page_url(page_response, page_number:)
-          raise NotImplementedError, "#{self.class}#next_page_url must be implemented by subclass"
-        end
       end
     end
   end

data/lib/html2rss/request_session/pager/custom_selector.rb

@@ -11,7 +11,7 @@ module Html2rss
         # @param page_response [RequestService::Response]
         # @param page_number [Integer]
         # @return [String, nil]
-        def next_page_url(page_response, page_number: nil) # rubocop:disable Lint/UnusedMethodArgument
+        def next_page_url(page_response, page_number:) # rubocop:disable Lint/UnusedMethodArgument
           selector = config[:selector]
           return nil if selector.nil? || selector.empty?
 
@@ -19,16 +19,16 @@ module Html2rss
           return nil unless node
 
           href = node['href'] || node.text
-          return nil if href.nil? || href.strip.empty?
+          return nil if href.strip.empty?
 
-          Html2rss::Url.from_relative(href.strip, page_response.url)
+          Html2rss::Url.from_relative(href, page_response.url)
         end
 
         # @param parsed_body [Nokogiri::HTML::Document]
         # @param selector [String]
         # @return [Nokogiri::XML::Node, nil]
         def extract_node(parsed_body, selector)
-          parsed_body.at_css(selector) || parsed_body.at_xpath(selector)
+          parsed_body.at_css(selector)
         rescue Nokogiri::CSS::SyntaxError, Nokogiri::XML::XPath::SyntaxError
           # Pure XPath like `descendant::a` fails LOOKS_LIKE_XPATH / at_css; fall back explicitly.
           parsed_body.at_xpath(selector)

data/lib/html2rss/request_session/pager/offset.rb

@@ -25,14 +25,8 @@ module Html2rss
         # @return [Html2rss::Url]
         def next_page_url(page_response, page_number:)
           param = config.fetch(:param, DEFAULT_PARAM)
-          target_offset_val = target_offset_for(page_number)
           url = Html2rss::Url.from_absolute(page_response.url)
-
-          if url.to_s.include?('{offset}')
-            Html2rss::Url.from_absolute(url.to_s.gsub('{offset}', target_offset_val.to_s))
-          else
-            url.with_query_values(url.query_values.merge(param.to_s => target_offset_val.to_s))
-          end
+          url.with_query_values(url.query_values.merge(param.to_s => target_offset_for(page_number).to_s))
         end
 
         # @param page_number [Integer]

data/lib/html2rss/request_session/pager/rel_next.rb

@@ -11,7 +11,7 @@ module Html2rss
         # @param page_response [RequestService::Response]
         # @param page_number [Integer]
         # @return [String, nil]
-        def next_page_url(page_response, page_number: nil) # rubocop:disable Lint/UnusedMethodArgument
+        def next_page_url(page_response, page_number:) # rubocop:disable Lint/UnusedMethodArgument
           href = page_response.parsed_body.at_css('link[rel~="next"][href], a[rel~="next"][href]')&.[]('href')
           return nil if href.nil? || href.empty?
 

data/lib/html2rss/request_session/pager/url_template.rb

@@ -25,14 +25,8 @@ module Html2rss
         # @return [Html2rss::Url]
         def next_page_url(page_response, page_number:)
           param = config.fetch(:param, DEFAULT_PARAM)
-          target_page_val = target_page_for(page_number)
           url = Html2rss::Url.from_absolute(page_response.url)
-
-          if url.to_s.include?('{page}')
-            Html2rss::Url.from_absolute(url.to_s.gsub('{page}', target_page_val.to_s))
-          else
-            url.with_query_values(url.query_values.merge(param.to_s => target_page_val.to_s))
-          end
+          url.with_query_values(url.query_values.merge(param.to_s => target_page_for(page_number).to_s))
         end
 
         # @param page_number [Integer]

data/lib/html2rss/request_session/pager.rb

@@ -47,7 +47,7 @@ module Html2rss
         strategy_name = normalized_config.fetch(:strategy, :rel_next).to_sym
 
         klass = STRATEGIES.fetch(strategy_name) do
-          raise ArgumentError, "Unknown pagination strategy: #{strategy_name}"
+          raise InvalidOption, "Unknown pagination strategy: #{strategy_name}"
         end
 
         klass.new(session:, initial_response:, config: normalized_config)

data/lib/html2rss/request_session.rb

@@ -65,9 +65,13 @@ module Html2rss
     # @param url [String, Html2rss::Url] follow-up request url
     # @param relation [Symbol] why the follow-up is being made
     # @param origin_url [String, Html2rss::Url] effective origin for same-origin checks
+    # @param advertisement [RequestService::FeedAdvertisement, nil] the origin page's advertised feeds;
+    #   with relation +:advertised_feed+, {RequestService::Policy} lets a listed feed leave the origin
     # @return [RequestService::Response] follow-up response
-    def follow_up(url:, relation:, origin_url:)
-      execute(context.follow_up(url:, relation:, origin_url:)).tap { |response| remember!(response.url) }
+    def follow_up(url:, relation:, origin_url:, advertisement: nil)
+      execute(context.follow_up(url:, relation:, origin_url:, advertisement:)).tap do |response|
+        remember!(response.url)
+      end
     end
 
     ##

data/lib/html2rss/scoring/cluster_scorer.rb

@@ -72,7 +72,7 @@ module Html2rss
       end
 
       def text_words(node)
-        @text_words[node] ||= node.word_count
+        @text_words[node] ||= node.run_count
       end
 
       def date?(node)

data/lib/html2rss/scoring/container_assessor.rb

@@ -7,6 +7,8 @@ module Html2rss
     class ContainerAssessor
       # Microdata itemprop values treated as publish/update markers.
       PUBLISH_ITEMPROPS = %w[datePublished dateModified].freeze
+      # Letter/digit runs ({WordCount.runs}) beyond the title that make a container descriptive.
+      DESCRIPTIVE_RUNS = 8
 
       # @param text_classifier [LinkDestination::TextClassifier]
       # @param content_token_regexp [Regexp]
@@ -25,11 +27,12 @@ module Html2rss
       # @param destination_facts [LinkDestination::DestinationFacts, nil]
       # @return [Observation]
       def call(container, selected_anchor, destination_facts:) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
-        title = entry_title(container, selected_anchor)
+        source = container.find(&:heading?) || selected_anchor
+        title = source ? source.visible_text.to_s.strip : ''
         tokens = "#{container.attrs.class_attr} #{container.attrs.id}"
 
         Observation.new(
-          title_word_count: word_count(title),
+          title_runs: source ? source.run_count : 0,
           path_length: destination_facts&.url&.path.to_s.length,
           content_path: destination_facts&.content_path,
           publish_marker: publish_marker?(container),
@@ -59,20 +62,16 @@ module Html2rss
       end
 
       def descriptive_context?(container_text, title)
-        snippet = container_text.to_s.sub(/\A#{Regexp.escape(title.to_s)}/i, '')
-        snippet.length > 30 && word_count(snippet) >= 8
+        snippet = without_title_prefix(container_text.to_s, title)
+        snippet.length > 30 && WordCount.runs(snippet, ceiling: DESCRIPTIVE_RUNS) == DESCRIPTIVE_RUNS
       end
 
-      def entry_title(container, selected_anchor)
-        heading = container.find(&:heading?)
-        source = heading || selected_anchor
-        source ? source.visible_text.to_s.strip : ''
-      end
+      # Case-insensitive prefix strip compared by character count, so multi-character
+      # case folds (e.g. "ß" vs "ss") do not match; the title is then left in the snippet.
+      def without_title_prefix(text, title)
+        return text unless text[0, title.length].casecmp?(title)
 
-      def word_count(text)
-        count = 0
-        text.to_s.scan(/\p{Alnum}+/) { count += 1 }
-        count
+        text[title.length..]
       end
     end
   end

data/lib/html2rss/scoring/engine.rb

@@ -11,7 +11,7 @@ module Html2rss
       SCORE_FLOOR = 0.0
 
       FEATURE_IDS = Set[
-        :title_word_count_ge3, :title_word_count_ge7, :path_length_gt6, :content_path,
+        :title_runs_ge3, :title_runs_ge7, :path_length_gt6, :content_path,
         :publish_marker, :descriptive_context, :article_container, :content_tokens,
         :non_content_utility_path, :utility_prefix_title_short, :shallow, :weak_container,
         :recommended_title_non_content, :high_confidence_junk_path, :junk_tokens,
@@ -22,8 +22,8 @@ module Html2rss
 
       # Quality feature triples: [feature_id, predicate, weight].
       QUALITY_RULES = [
-        [:title_word_count_ge3, ->(o) { o.title_word_count >= 3 }, 40],
-        [:title_word_count_ge7, ->(o) { o.title_word_count >= 7 }, 15],
+        [:title_runs_ge3, ->(o) { o.title_runs >= 3 }, 40],
+        [:title_runs_ge7, ->(o) { o.title_runs >= 7 }, 15],
         [:path_length_gt6, ->(o) { o.path_length > 6 }, 20],
         [:content_path, lambda(&:content_path), 15],
         [:publish_marker, lambda(&:publish_marker), 15],
@@ -35,7 +35,7 @@ module Html2rss
       # Junk feature triples: [feature_id, predicate, weight].
       JUNK_RULES = [
         [:non_content_utility_path, ->(o) { o.utility_path && !o.content_path && !o.strong_post_suffix }, 25],
-        [:utility_prefix_title_short, ->(o) { o.utility_prefix_title && o.title_word_count <= 6 }, 15],
+        [:utility_prefix_title_short, ->(o) { o.utility_prefix_title && o.title_runs <= 6 }, 15],
         [:shallow, lambda(&:shallow), 10],
         [:weak_container, ->(o) { !o.publish_marker && !o.descriptive_context }, 10],
         [:recommended_title_non_content, ->(o) { o.recommended_title && !o.content_path }, 10],
@@ -46,9 +46,9 @@ module Html2rss
       ##
       # @param id [Symbol]
       # @return [Symbol]
-      # @raise [ArgumentError] when id is not in the closed set
+      # @raise [InvalidOption] when id is not in the closed set
       def self.assert_feature_id!(id)
-        raise ArgumentError, "unknown feature: #{id.inspect}" unless FEATURE_IDS.include?(id)
+        raise InvalidOption, "unknown feature: #{id.inspect}" unless FEATURE_IDS.include?(id)
 
         id
       end
@@ -91,21 +91,17 @@ module Html2rss
 
       private
 
-      def rank_one(segment, hard_junk_mode: :strict) # rubocop:disable Metrics/MethodLength
+      def rank_one(segment, hard_junk_mode: :strict) # rubocop:disable Metrics/AbcSize
         facts = segment.primary_link ? @link_resolver.destination_facts(segment.primary_link) : nil
         obs = @assessor.call(segment.root_node, segment.primary_link, destination_facts: facts)
         return if obs.hard_junk?(mode: hard_junk_mode)
 
         quality, quality_parts = apply_rules(QUALITY_RULES, obs)
         junk, junk_parts = apply_rules(JUNK_RULES, obs)
-        ranked(
+        RankedSegment.new(
           segment:,
-          score: build_score(
-            composite: quality - junk,
-            quality:,
-            junk:,
-            breakdown: quality_parts.merge(junk_parts)
-          )
+          score: Score.new(composite: (quality - junk).to_f, quality: quality.to_f, junk: junk.to_f,
+                           breakdown: quality_parts.merge(junk_parts).freeze)
         )
       end
 
@@ -116,30 +112,6 @@ module Html2rss
         end
         [parts.values.sum, parts]
       end
-
-      def build_score(composite:, quality: nil, junk: nil, breakdown: nil)
-        raise ArgumentError, 'composite must be Numeric' unless composite.is_a?(Numeric)
-
-        Score.new(
-          composite: composite.to_f,
-          quality: (quality.nil? ? composite : quality).to_f,
-          junk: (junk || 0).to_f,
-          breakdown: normalize_breakdown(breakdown)
-        )
-      end
-
-      def normalize_breakdown(breakdown)
-        return Score::EMPTY_BREAKDOWN if breakdown.nil?
-
-        breakdown.transform_keys { |id| self.class.assert_feature_id!(id) }.freeze
-      end
-
-      def ranked(segment:, score:)
-        raise ArgumentError, 'segment must be AutoSource::Segment' unless segment.is_a?(Html2rss::AutoSource::Segment)
-        raise ArgumentError, 'score must be Scoring::Score' unless score.is_a?(Score)
-
-        RankedSegment.new(segment:, score:)
-      end
     end
   end
 end

data/lib/html2rss/scoring/link_resolver.rb

@@ -24,7 +24,6 @@ module Html2rss
       def initialize(base_url)
         @base_url = base_url
         @by_href = {}
-        @by_node = {}.compare_by_identity
         @text_classifier = LinkDestination::TextClassifier.new
       end
 
@@ -35,15 +34,11 @@ module Html2rss
       # @param node_or_href [SST::Node, String, #to_s]
       # @return [LinkDestination::DestinationFacts, nil]
       def destination_facts(node_or_href)
-        return @by_node[node_or_href] if node_or_href.is_a?(SST::Node) && @by_node.key?(node_or_href)
-
         href = extract_href(node_or_href)
         return unless href
 
-        facts = (@by_href[href] ||= build_facts(href))
-        @by_node[node_or_href] = facts if node_or_href.is_a?(SST::Node)
-        facts
-      rescue ArgumentError
+        @by_href[href] ||= build_facts(href)
+      rescue Html2rss::Url::InvalidUrlError
         nil
       end
 

data/lib/html2rss/scoring/observation.rb

@@ -3,7 +3,7 @@
 module Html2rss
   module Scoring
     Observation = Data.define(
-      :title_word_count,
+      :title_runs,
       :path_length,
       :content_path,
       :publish_marker,
@@ -40,7 +40,7 @@ module Html2rss
         when :lenient
           (high_confidence_junk_path && weak_signals?) || chrome_title_junk?
         else
-          raise ArgumentError, "unknown hard_junk mode: #{mode.inspect}"
+          raise InvalidOption, "unknown hard_junk mode: #{mode.inspect}"
         end
       end
 

data/lib/html2rss/selector_candidates.rb

@@ -8,7 +8,12 @@ module Html2rss
   # Does not emit the default +a[href]+ fallback — that remains Capture's YAML path only.
   class SelectorCandidates # rubocop:disable Metrics/ClassLength -- ranking + field CSS stay co-located
     # Empty candidate buckets (no discovered evidence).
-    EMPTY = { items: [].freeze, title: [].freeze, link: [].freeze, published: [].freeze }.freeze
+    EMPTY = {
+      items: [].freeze, title: [].freeze, link: [].freeze, published: [].freeze, candidates_by_item: [].freeze
+    }.freeze
+
+    # How many top-ranked item candidates get their own field buckets in +:candidates_by_item+.
+    BY_ITEM_LIMIT = 5
 
     # Ranking preference for items selector derivation kind (lower is better).
     KIND_RANK = { shared_class: 0, unique_tag: 1, path: 2 }.freeze
@@ -22,8 +27,8 @@ module Html2rss
     DEFAULT_MIN_MATCHES = 2
     private_constant :DEFAULT_MIN_MATCHES
 
-    # Class token that identifies a non-heading title node. Same pattern title_node matches.
-    TITLE_CLASS_PATTERN = /title|font-bold|font-semibold/
+    # Class token that identifies a non-heading title node. Owned by the extractor so both match the same nodes.
+    TITLE_CLASS_PATTERN = Html::SstArticleExtractor::TITLE_CLASS_PATTERN
     private_constant :TITLE_CLASS_PATTERN
 
     class << self
@@ -37,7 +42,8 @@ module Html2rss
       # @param items_evidence [Array<Hash>] each with +:selector+, +:enhance+, +:strategy+,
       #   +:kind+, +:match_count+, and +:roots+ (SST nodes under the items selector)
       # @param min_matches [Integer] minimum repeated field evidence across roots
-      # @return [Hash{Symbol=>Array<Hash>}] +:items+, +:title+, +:link+, +:published+
+      # @return [Hash{Symbol=>Array<Hash>}] +:items+, +:title+, +:link+, +:published+ (buckets for the
+      #   top item) and +:candidates_by_item+ (per-item buckets for the top {BY_ITEM_LIMIT} items)
       def call(items_evidence:, min_matches: DEFAULT_MIN_MATCHES)
         new(items_evidence:, min_matches:).call
       end
@@ -57,17 +63,22 @@ module Html2rss
       items = rank_items(@items_evidence)
       return EMPTY if items.empty?
 
-      roots = roots_for(items.first, @items_evidence)
+      by_item = items.first(BY_ITEM_LIMIT).map { |item| item_buckets(item) }
+      { items:, **by_item.first.slice(:title, :link, :published), candidates_by_item: by_item }
+    end
+
+    private
+
+    def item_buckets(item)
+      roots = roots_for(item, @items_evidence)
       {
-        items:,
+        selector: item.fetch(:selector),
         title: field_bucket(roots, :title),
         link: field_bucket(roots, :link),
         published: field_bucket(roots, :published)
       }
     end
 
-    private
-
     def rank_items(evidence)
       evidence
         .sort_by { |entry| item_rank_key(entry) }

data/lib/html2rss/selectors/README.md

@@ -11,7 +11,7 @@ YAML / MCP wire vocabulary is unchanged (`selectors`, `extractor`, `post_process
 ## Live flow
 
 1. **Parse** — HTML stays on `Response#parsed_body`. JSON responses are converted once via `JsonXml` into an HTML5 fragment so CSS selectors still run.
-2. **Items** — `items.selector` finds each card/node. Omitted, blank, and `Selectors::DEFAULT_ITEMS_SELECTOR` expand to `Html::Navigator::MAIN_ANCHOR_SELECTOR` (permalink anchors). Any other selector, including `a` and `.card`, is used as written. `Config.prepare_defaults` fills that default, with `enhance: true`, only when `selectors:` is present. `enhance: true` fills missing fields via `Html::ArticleExtractor` (list-card enrichment). Enhancement is skipped when title, url, description, published_at, enclosures, and categories are already populated.
+2. **Items** — `items.selector` finds each card/node. Omitted, blank, and `Selectors::DEFAULT_ITEMS_SELECTOR` expand to `Html::Navigator::MAIN_ANCHOR_SELECTOR` (permalink anchors). Any other selector, including `a` and `.card`, is used as written. `Config.prepare_defaults` fills that default, with `enhance: true`, only when `selectors:` is present. `enhance: true` fills missing fields via `Html::ArticleExtractor` (list-card enrichment); an item with no link of its own gets no `url`, never a `page#id` fragment, and is left out of the feed (`Article#linked?`, the rule auto-source applies too). An item needs a resolvable link: configure a `url` selector when the items are not anchors or do not contain one. Enhancement is skipped when title, url, description, published_at, enclosures, and categories are already populated.
 3. **Field dispatch** (private on `Selectors`) — for each selectable key (`title`, `url`, `enclosure`, `categories`, …):
    - Regular fields → `Extractors.call` → optional `PostProcessors.call` chain
    - Special keys → enclosure wrap, guid fan-out, multi-node categories

data/lib/html2rss/selectors/extractors/href.rb

@@ -54,11 +54,9 @@ module Html2rss
         ##
         # Retrieves and returns the normalized absolute URL.
         #
-        # @return [Html2rss::Url, nil] The absolute URL.
+        # @return [Html2rss::Url, nil] The absolute URL, or nil when nothing matched or the +href+ is blank.
         def call
-          return nil unless @href
-
-          Url.from_relative(@href, @base_url)
+          Url.from_relative(@href, @base_url) unless @href.strip.empty?
         end
       end
     end

data/lib/html2rss/selectors/json_xml.rb

@@ -14,48 +14,47 @@ module Html2rss
         array: ['<array>', '</array>']
       }.freeze
 
-      module_function
-
-      ##
-      # Converts the object to XML format.
-      #
-      # @param object [Object] any Ruby object (Hash, Array, String, Symbol, etc.)
-      # @return [String] representing the object in XML
-      def call(object)
-        object_to_xml(object).tap do |converted|
-          Html2rss::Log.debug("#{self}: converted object to XML (#{converted.bytesize} bytes)")
+      class << self
+        ##
+        # Converts the object to XML format.
+        #
+        # @param object [Object] any Ruby object (Hash, Array, String, Symbol, etc.)
+        # @return [String] representing the object in XML
+        def call(object)
+          object_to_xml(object).tap do |converted|
+            Html2rss::Log.debug("#{self}: converted object to XML (#{converted.bytesize} bytes)")
+          end
         end
-      end
 
-      def object_to_xml(object)
-        case object
-        when Hash
-          hash_to_xml(object)
-        when Array
-          array_to_xml(object)
-        else
-          CGI.escapeHTML(object.to_s)
+        private
+
+        def object_to_xml(object)
+          case object
+          when Hash
+            hash_to_xml(object)
+          when Array
+            array_to_xml(object)
+          else
+            CGI.escapeHTML(object.to_s)
+          end
         end
-      end
-      private_class_method :object_to_xml
 
-      def hash_to_xml(object)
-        prefix, suffix = OBJECT_TO_XML_TAGS[:hash]
-        inner_xml = object.each_with_object(+'') do |(key, value), str|
-          str << "<#{key}>#{object_to_xml(value)}</#{key}>"
-        end
+        def hash_to_xml(object)
+          prefix, suffix = OBJECT_TO_XML_TAGS[:hash]
+          inner_xml = object.each_with_object(+'') do |(key, value), str|
+            str << "<#{key}>#{object_to_xml(value)}</#{key}>"
+          end
 
-        "#{prefix}#{inner_xml}#{suffix}"
-      end
-      private_class_method :hash_to_xml
+          "#{prefix}#{inner_xml}#{suffix}"
+        end
 
-      def array_to_xml(object)
-        prefix, suffix = OBJECT_TO_XML_TAGS[:array]
-        inner_xml = object.each_with_object(+'') { |value, str| str << object_to_xml(value) }
+        def array_to_xml(object)
+          prefix, suffix = OBJECT_TO_XML_TAGS[:array]
+          inner_xml = object.each_with_object(+'') { |value, str| str << object_to_xml(value) }
 
-        "#{prefix}#{inner_xml}#{suffix}"
+          "#{prefix}#{inner_xml}#{suffix}"
+        end
       end
-      private_class_method :array_to_xml
     end
   end
 end