html2rss 0.32.4 → 0.33.0

data/lib/html2rss/error.rb

@@ -40,10 +40,10 @@ module Html2rss
     attr_accessor :transport_meta
 
     # @return [String, nil] scrape-api timeout stage when known (overridden by RequestTimedOut)
-    def timeout_phase = nil
+    def timeout_phase; end
 
     # @return [Symbol, nil] surface classification when known (overridden by NoFeedItemsExtracted)
-    def surface_category = nil
+    def surface_category; end
 
     ##
     # Sparse telemetry hash for observability consumers.
@@ -59,6 +59,9 @@ module Html2rss
     end
   end
 
+  # Raised when a caller-supplied option value is malformed or out of range.
+  class InvalidOption < Error; end
+
   # 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.
@@ -87,7 +90,8 @@ module Html2rss
 
     def base_message
       summaries = attempts.map do |attempt|
-        details = attempt[:items_count].nil? ? "#{attempt[:error_class]} error" : "#{attempt[:items_count]} items"
+        count = attempt[:items_count]
+        details = count.nil? ? "#{attempt[:error_class]} error" : "#{count} items"
         "#{attempt[:strategy]} (#{details})"
       end.join(', ')
 

data/lib/html2rss/feed_builder/rss.rb

@@ -37,7 +37,7 @@ module Html2rss
           item_maker.title = article.title
           item_maker.author = article.author
           description = ItemPresentation.description_for(article)
-          item_maker.description = description if description && !description.empty?
+          item_maker.description = description if description
           item_maker.link = article.url.to_s if article.url
           item_maker.pubDate = article.published_at&.rfc2822
         end

data/lib/html2rss/feed_pipeline/auto_fallback.rb

@@ -83,7 +83,7 @@ module Html2rss
         # @param elapsed_ms [Integer, nil] monotonic hop duration in milliseconds
         # @return [void]
         def record_error(strategy:, error:, elapsed_ms: nil)
-          meta = error.is_a?(Html2rss::Error) ? error.transport_meta : nil
+          meta = error.transport_meta if error.is_a?(Error)
           append_attempt(strategy:, error_class: error.class.name, transport_meta: meta, elapsed_ms:)
           @last_error = error
           return unless TERMINAL_TRANSPORT_ERRORS.any? { |klass| error.is_a?(klass) }
@@ -137,7 +137,7 @@ module Html2rss
         # @raise [Html2rss::Error, StandardError]
         def raise_failure!
           if (error = failure_error)
-            error.attempts = attempts if error.is_a?(Html2rss::Error)
+            error.attempts = attempts if error.is_a?(Error)
             raise error
           end
 
@@ -215,7 +215,7 @@ module Html2rss
       rescue *NON_FALLBACK_ERRORS => error
         state.record_error(strategy:, error:, elapsed_ms: monotonic_ms - started_ms)
         state.abort!
-      rescue StandardError => error
+      rescue Html2rss::Error => error
         state.record_error(strategy:, error:, elapsed_ms: monotonic_ms - started_ms)
         log_fallback_error(strategy:, next_strategy:, error:, request_session:) if next_strategy && request_session
       end

data/lib/html2rss/feed_resolution/candidate_generator.rb

@@ -50,7 +50,6 @@ module Html2rss
         return unless parsed_html
 
         url = Syndication::Discovery.candidate_urls(page_url: entry_url, parsed_body: parsed_html).first
-        return unless url
         return unless eligible_url?(url)
 
         url
@@ -86,6 +85,8 @@ module Html2rss
         return [] unless parsed_html
 
         sst = SST::Normalizer.call(parsed_html)
+        return [] unless sst
+
         link_resolver = Scoring::LinkResolver.new(entry_url)
 
         SEGMENT_STRATEGIES.each do |strategy|
@@ -93,8 +94,6 @@ module Html2rss
           return urls if urls.size >= 2
         end
         []
-      rescue StandardError
-        []
       end
 
       def segment_urls_for(sst, strategy, link_resolver)
@@ -120,7 +119,7 @@ module Html2rss
         return if href.nil? || href.empty? || href.start_with?('#', 'mailto:', 'javascript:')
 
         Html2rss::Url.from_relative(href, entry_url)
-      rescue ArgumentError
+      rescue Html2rss::Url::InvalidUrlError
         nil
       end
 

data/lib/html2rss/feed_resolution/options.rb

@@ -8,15 +8,11 @@ module Html2rss
     # Typed +auto_source.entry_resolution+ options (one expansion from config Hash).
     class Options
       ##
-      # @param auto_source [Hash, nil]
+      # @param auto_source [Hash, nil] validated +auto_source+ config
       # @return [Options]
       def self.from_auto_source(auto_source)
-        raw = auto_source.is_a?(Hash) ? auto_source[:entry_resolution] : nil
-        raw = {} unless raw.is_a?(Hash)
-        new(
-          enabled: raw.fetch(:enabled, FeedResolution::DEFAULT_CONFIG[:enabled]) != false,
-          max_probes: Integer(raw.fetch(:max_probes, FeedResolution::DEFAULT_CONFIG[:max_probes]))
-        )
+        raw = auto_source&.dig(:entry_resolution) || {}
+        new(enabled: raw.fetch(:enabled, true), max_probes: raw.fetch(:max_probes, DEFAULT_CONFIG[:max_probes]))
       end
 
       ##

data/lib/html2rss/feed_resolution/policy.rb

@@ -8,40 +8,36 @@ module Html2rss
       # Minimum admitted articles before the entry URL is considered strong enough.
       ARTICLE_FLOOR = 3
 
-      module_function
-
-      ##
-      # @param config [Html2rss::Config]
-      # @param articles [Array<Html2rss::Article>] typed extract results (count derived)
-      # @param surface_category [Html2rss::SurfaceCategory, Symbol]
-      # @return [Boolean]
-      def resolve?(config:, articles:, surface_category:)
-        raise ArgumentError, 'articles must be an Array' unless articles.is_a?(Array)
-        return false unless eligible_config?(config)
-
-        category = SurfaceCategory[surface_category]
-        return false if category.blocked?
-
-        articles.size < ARTICLE_FLOOR || category.weak? || native_feed_majority?(articles)
-      end
-
-      def eligible_config?(config)
-        return false unless config.auto_source
-        return false if config.selectors
-
-        Options.from_auto_source(config.auto_source).enabled?
-      end
-      module_function :eligible_config?
-      private_class_method :eligible_config?
-
-      def native_feed_majority?(articles)
-        return false if articles.empty?
-
-        native = articles.count { |article| article.scraper == AutoSource::Scraper::NativeFeed }
-        native * 2 >= articles.size
+      class << self
+        ##
+        # @param config [Html2rss::Config]
+        # @param articles [Array<Html2rss::Article>] typed extract results (count derived)
+        # @param surface_category [Html2rss::SurfaceCategory, Symbol]
+        # @return [Boolean]
+        def resolve?(config:, articles:, surface_category:)
+          raise ArgumentError, 'articles must be an Array' unless articles.is_a?(Array)
+          return false unless eligible_config?(config)
+
+          category = SurfaceCategory[surface_category]
+          return false if category.blocked?
+
+          articles.size < ARTICLE_FLOOR || category.weak? || native_feed_majority?(articles)
+        end
+
+        private
+
+        def eligible_config?(config)
+          return false unless config.auto_source
+          return false if config.selectors
+
+          Options.from_auto_source(config.auto_source).enabled?
+        end
+
+        def native_feed_majority?(articles)
+          native = articles.count { |article| article.scraper == AutoSource::Scraper::NativeFeed }
+          native * 2 >= articles.size
+        end
       end
-      module_function :native_feed_majority?
-      private_class_method :native_feed_majority?
     end
   end
 end

data/lib/html2rss/feed_resolution/probe.rb

@@ -16,7 +16,7 @@ module Html2rss
       # @param origin_url [String, Html2rss::Url]
       def initialize(request_session:, origin_url:)
         @request_session = request_session
-        @origin_url = Html2rss::Url.from_absolute(origin_url)
+        @origin_url = Url.from_absolute(origin_url)
       end
 
       ##
@@ -28,7 +28,7 @@ module Html2rss
           relation: :entry_resolution,
           origin_url:
         )
-        score_response(url, response)
+        score_response(response)
       rescue Html2rss::Error
         nil
       end
@@ -37,7 +37,7 @@ module Html2rss
 
       attr_reader :request_session, :origin_url
 
-      def score_response(_url, response) # rubocop:disable Metrics/MethodLength -- feed vs HTML branches
+      def score_response(response) # rubocop:disable Metrics/MethodLength -- feed vs HTML branches
         if response.feed_response?
           count = Syndication::Parser.parse_response(response).size
           return Scored.new(

data/lib/html2rss/feed_resolution/scorer.rb

@@ -11,38 +11,38 @@ module Html2rss
       # Bonus when the surface looks like a listing rather than a hub/shell.
       LISTING_SURFACE_BONUS = 5
 
-      module_function
+      class << self
+        ##
+        # @param articles_count [Integer]
+        # @return [Integer]
+        def score_feed(articles_count:)
+          articles_count * ARTICLE_WEIGHT
+        end
 
-      ##
-      # @param articles_count [Integer]
-      # @return [Integer]
-      def score_feed(articles_count:)
-        articles_count.to_i * ARTICLE_WEIGHT
-      end
-
-      ##
-      # @param assessment [Html2rss::PageRecon::Assessment]
-      # @return [Integer]
-      def score_assessment(assessment)
-        score = assessment.articles_count * ARTICLE_WEIGHT
-        score += LISTING_SURFACE_BONUS if assessment.listing_bonus?
-        drops = assessment.admission_drops.values.sum
-        total = assessment.articles_count + drops
-        score -= ((drops.to_f / total) * ARTICLE_WEIGHT).round if total.positive?
-        score
-      end
+        ##
+        # @param assessment [Html2rss::PageRecon::Assessment]
+        # @return [Integer]
+        def score_assessment(assessment)
+          score = assessment.articles_count * ARTICLE_WEIGHT
+          score += LISTING_SURFACE_BONUS if assessment.listing_bonus?
+          drops = assessment.admission_drops.values.sum
+          total = assessment.articles_count + drops
+          score -= ((drops.to_f / total) * ARTICLE_WEIGHT).round if total.positive?
+          score
+        end
 
-      ##
-      # @param scored [Array<Probe::Scored>]
-      # @param entry_articles_count [Integer]
-      # @return [Probe::Scored, nil]
-      def pick_winner(scored:, entry_articles_count:)
-        winner = scored.max_by(&:score)
-        return unless winner
-        return if winner.articles_count <= entry_articles_count.to_i
-        return if winner.score <= 0
+        ##
+        # @param scored [Array<Probe::Scored>]
+        # @param entry_articles_count [Integer]
+        # @return [Probe::Scored, nil]
+        def pick_winner(scored:, entry_articles_count:)
+          winner = scored.max_by(&:score)
+          return unless winner
+          return if winner.articles_count <= entry_articles_count.to_i
+          return if winner.score <= 0
 
-        winner
+          winner
+        end
       end
     end
   end

data/lib/html2rss/feed_resolution.rb

@@ -116,17 +116,13 @@ module Html2rss
         return unless resolution.applied
 
         effective = scrape_target.with_effective(resolution.scrape_url)
-        return ApplyOutcome.new(scrape_target: effective, status: :succeeded) if retry_with(
-          resolution, effective:
-        )
-
-        nil
+        ApplyOutcome.new(scrape_target: effective, status: :succeeded) if retry_with(effective:)
       rescue RequestService::RequestBudgetExceeded
         log_budget_exhausted
         nil
       rescue *NON_FALLBACK_ERRORS
         raise
-      rescue StandardError => error
+      rescue Html2rss::Error => error
         log_retry_failed(error)
         nil
       end
@@ -158,7 +154,7 @@ module Html2rss
       # @return [String, nil]
       def channel_host
         Url.from_absolute(config.url.to_s).host
-      rescue ArgumentError
+      rescue Html2rss::Url::InvalidUrlError
         nil
       end
 
@@ -184,7 +180,7 @@ module Html2rss
         )
       end
 
-      def retry_with(_resolution, effective:) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- retry extract path
+      def retry_with(effective:) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- retry extract path
         retry_session = pipeline.request_session_for(
           config, strategy:, resources:, scrape_url: effective.effective_url
         )
@@ -220,7 +216,7 @@ module Html2rss
       def initialize(entry_url:, response:, session:, config:, articles:, surface_category: nil)
         raise ArgumentError, 'articles must be an Array' unless articles.is_a?(Array)
 
-        @entry_url = Html2rss::Url.from_absolute(entry_url)
+        @entry_url = Url.from_absolute(entry_url)
         @response = response
         @session = session
         @config = config

data/lib/html2rss/feed_result.rb

@@ -23,8 +23,7 @@ module Html2rss
     def initialize(channel:, articles:, status:, stylesheets: [])
       raise ArgumentError, 'channel must be a Html2rss::Channel' unless channel.is_a?(Channel)
       raise ArgumentError, 'status must be a Html2rss::Status' unless status.is_a?(Status)
-
-      articles = Array(articles)
+      raise ArgumentError, 'articles must be an Array' unless articles.is_a?(Array)
       raise ArgumentError, 'articles must all be Html2rss::Article' unless articles.all?(Article)
 
       @channel = channel
@@ -82,7 +81,9 @@ module Html2rss
     end
 
     def freeze_stylesheets(stylesheets)
-      Array(stylesheets).map do |sheet|
+      raise ArgumentError, 'stylesheets must be an Array' unless stylesheets.is_a?(Array)
+
+      stylesheets.map do |sheet|
         sheet.to_h.transform_keys(&:to_sym).transform_values do |value|
           value.is_a?(String) ? value.dup.freeze : value
         end.freeze

data/lib/html2rss/hash_util.rb

@@ -3,116 +3,117 @@
 module Html2rss
   # Shared helpers for hash normalization and structural operations.
   module HashUtil
-    module_function
+    class << self
+      # Deeply duplicates nested arrays and hashes.
+      #
+      # @param object [Object] nested value from configuration or runtime state
+      # @return [Object] deep duplicated object
+      def deep_dup(object)
+        case object
+        in Hash
+          object.transform_values { deep_dup(_1) }
+        in Array
+          object.map { deep_dup(_1) }
+        else
+          object.dup
+        end
+      end
 
-    # Deeply duplicates nested arrays and hashes.
-    #
-    # @param object [Object] nested value from configuration or runtime state
-    # @return [Object] deep duplicated object
-    def deep_dup(object)
-      case object
-      in Hash
-        object.transform_values { deep_dup(_1) }
-      in Array
-        object.map { deep_dup(_1) }
-      else
-        object.dup rescue StandardError # rubocop:disable Style/RescueModifier
+      # Deeply merges nested hashes while replacing non-hash values from override.
+      #
+      # @param base [Hash] base hash
+      # @param override [Hash] override hash
+      # @return [Hash] merged hash
+      def deep_merge(base, override)
+        base.merge(override) do |_key, old_val, new_val|
+          case [old_val, new_val]
+          in [Hash, Hash]
+            deep_merge(old_val, new_val)
+          else
+            new_val
+          end
+        end
       end
-    end
 
-    # Deeply merges nested hashes while replacing non-hash values from override.
-    #
-    # @param base [Hash] base hash
-    # @param override [Hash] override hash
-    # @return [Hash] merged hash
-    def deep_merge(base, override)
-      base.merge(override) do |_key, old_val, new_val|
-        case [old_val, new_val]
-        in [Hash, Hash]
-          deep_merge(old_val, new_val)
+      # Converts string-keyed hashes to symbol-keyed hashes recursively.
+      #
+      # @param object [Object] value to normalize
+      # @param context [String] error context
+      # @return [Object] normalized value
+      def deep_symbolize_keys(object, context: 'hash')
+        case object
+        in Hash
+          object.each_with_object({}) do |(k, v), memo|
+            memo[symbol_key(k, context:)] = deep_symbolize_keys(v, context:)
+          end
+        in Array
+          object.map { deep_symbolize_keys(_1, context:) }
         else
-          new_val
+          object
         end
       end
-    end
 
-    # Converts string-keyed hashes to symbol-keyed hashes recursively.
-    #
-    # @param object [Object] value to normalize
-    # @param context [String] error context
-    # @return [Object] normalized value
-    def deep_symbolize_keys(object, context: 'hash')
-      case object
-      in Hash
-        object.each_with_object({}) do |(k, v), memo|
-          memo[symbol_key(k, context:)] = deep_symbolize_keys(v, context:)
+      # Converts hash keys (and Symbol values) to strings recursively.
+      #
+      # @param object [Object] value to normalize
+      # @return [Object] normalized value with string keys
+      def deep_stringify_keys(object)
+        case object
+        when Hash
+          object.to_h { |key, value| [key.to_s, deep_stringify_keys(value)] }
+        when Array
+          object.map { deep_stringify_keys(_1) }
+        when Symbol
+          object.to_s
+        else
+          object
         end
-      in Array
-        object.map { deep_symbolize_keys(_1, context:) }
-      else
-        object
       end
-    end
 
-    # Converts hash keys (and Symbol values) to strings recursively.
-    #
-    # @param object [Object] value to normalize
-    # @return [Object] normalized value with string keys
-    def deep_stringify_keys(object)
-      case object
-      when Hash
-        object.to_h { |key, value| [key.to_s, deep_stringify_keys(value)] }
-      when Array
-        object.map { deep_stringify_keys(_1) }
-      when Symbol
-        object.to_s
-      else
-        object
-      end
-    end
+      # Validates that hash keys are symbols.
+      #
+      # @param value [Object] candidate hash container whose keys must be symbols
+      # @param context [String] error context
+      # @param deep [Boolean] whether nested hashes should also be validated
+      # @return [void]
+      def assert_symbol_keys!(value, context: 'hash', deep: true)
+        return unless value in Hash
 
-    # Validates that hash keys are symbols.
-    #
-    # @param value [Object] candidate hash container whose keys must be symbols
-    # @param context [String] error context
-    # @param deep [Boolean] whether nested hashes should also be validated
-    # @return [void]
-    def assert_symbol_keys!(value, context: 'hash', deep: true)
-      return unless value in Hash
+        unless value.each_key.all?(Symbol)
+          invalid_key = value.keys.find { _1.class != Symbol }
+          raise ArgumentError, "#{context} must use symbol keys (found #{invalid_key.inspect})"
+        end
 
-      unless value.each_key.all?(Symbol)
-        invalid_key = value.keys.find { _1.class != Symbol }
-        raise ArgumentError, "#{context} must use symbol keys (found #{invalid_key.inspect})"
+        value.each_value { assert_symbol_keys!(_1, context:, deep:) } if deep
       end
 
-      value.each_value { assert_symbol_keys!(_1, context:, deep:) } if deep
-    end
+      # Validates that hash keys are strings.
+      #
+      # @param value [Object] candidate hash container whose keys must be strings
+      # @param context [String] error context
+      # @param deep [Boolean] whether nested hashes should also be validated
+      # @return [void]
+      def assert_string_keys!(value, context: 'hash', deep: true)
+        return unless value in Hash
 
-    # Validates that hash keys are strings.
-    #
-    # @param value [Object] candidate hash container whose keys must be strings
-    # @param context [String] error context
-    # @param deep [Boolean] whether nested hashes should also be validated
-    # @return [void]
-    def assert_string_keys!(value, context: 'hash', deep: true)
-      return unless value in Hash
+        unless value.each_key.all?(String)
+          invalid_key = value.keys.find { _1.class != String }
+          raise ArgumentError, "#{context} must use string keys (found #{invalid_key.inspect})"
+        end
 
-      unless value.each_key.all?(String)
-        invalid_key = value.keys.find { _1.class != String }
-        raise ArgumentError, "#{context} must use string keys (found #{invalid_key.inspect})"
+        value.each_value { assert_string_keys!(_1, context:, deep:) } if deep
       end
 
-      value.each_value { assert_string_keys!(_1, context:, deep:) } if deep
-    end
+      private
 
-    def symbol_key(key, context:)
-      case key
-      in Symbol then key
-      in String then key.to_sym
-      else
-        raise ArgumentError, "#{context} must use string or symbol keys (found #{key.inspect})"
+      def symbol_key(key, context:)
+        case key
+        in Symbol then key
+        in String then key.to_sym
+        else
+          raise ArgumentError, "#{context} must use string or symbol keys (found #{key.inspect})"
+        end
       end
     end
-    private_class_method :symbol_key
   end
 end

data/lib/html2rss/html/article_extractor/category_extractor.rb

@@ -28,23 +28,20 @@ module Html2rss
         def self.call(article_tag, title: nil)
           return [] unless article_tag
 
-          extract_all_categories(article_tag, title:)
-            .map(&:strip)
-            .reject(&:empty?)
+          extract_all_categories(article_tag, title:).to_a
         end
 
         ##
         # Optimized single DOM traversal that extracts all category types.
+        # `Node#css` only yields descendants, so the container itself is never visited.
         #
         # @param article_tag [Nokogiri::XML::Element] The article element
         # @param title [String, nil]
         # @return [Set<String>] Set of category strings
-        def self.extract_all_categories(article_tag, title: nil)
+        def self.extract_all_categories(article_tag, title:)
           Set.new.tap do |categories|
             extract_element_data_categories!(categories, article_tag, title:)
             article_tag.css(CATEGORY_SELECTORS.join(',')).each do |element|
-              next if element == article_tag
-
               if ArticleRules::Category.class_match?(element['class'])
                 extract_text_categories!(categories, element, title:)
               end
@@ -60,7 +57,7 @@ module Html2rss
         # @param element [Nokogiri::XML::Element] metadata element that may contain category links
         # @param title [String, nil]
         # @return [void]
-        def self.extract_element_data_categories!(categories, element, title: nil)
+        def self.extract_element_data_categories!(categories, element, title:)
           element.attributes.each_value do |attr|
             next unless ArticleRules::Category.attr_name_match?(attr.name)
 
@@ -75,7 +72,7 @@ module Html2rss
         # @param element [Nokogiri::XML::Element] metadata element whose text may contain delimiters
         # @param title [String, nil]
         # @return [void]
-        def self.extract_text_categories!(categories, element, title: nil)
+        def self.extract_text_categories!(categories, element, title:)
           return if category_container?(element)
 
           anchors = element.name == 'a' ? [element] : element.css('a').to_a
@@ -96,7 +93,7 @@ module Html2rss
         # @param element [Nokogiri::XML::Element] The element to extract text from
         # @param title [String, nil]
         # @return [void]
-        def self.add_text_to_categories!(categories, element, title: nil)
+        def self.add_text_to_categories!(categories, element, title:)
           ArticleRules::Category.add_text!(categories, Navigator.extract_visible_text(element), title:)
         end
 

data/lib/html2rss/html/article_extractor/date_extractor.rb

@@ -9,7 +9,7 @@ module Html2rss
         # @param leftover_lines [Array<String>] leftover visible lines (already split)
         # @param time_zone [String] channel time zone for naive values
         # @return [DateTime, nil]
-        def self.call(article_tag, leftover_lines: [], time_zone: 'UTC')
+        def self.call(article_tag, time_zone:, leftover_lines: [])
           datetimes = article_tag.css('[datetime]').map { |tag| tag['datetime'] }
           ArticleRules::Date.earliest(datetimes, leftover_lines:, time_zone:)
         end

data/lib/html2rss/html/article_extractor/enclosure_extractor.rb

@@ -23,8 +23,6 @@ module Html2rss
         # @param base_url [String, Html2rss::Url] base URL for relative enclosure links
         # @return [Array<Hash{Symbol => Object}>] normalized enclosure hashes
         def self.call(article_tag, base_url)
-          return [] unless article_tag
-
           article_tag.css(SELECTOR).filter_map do |element|
             extract_from_element(element, base_url)
           end
@@ -34,7 +32,7 @@ module Html2rss
           case element.name
           when 'img'
             ArticleRules::Enclosure.from_image(element['src'], base_url)
-          when 'video', 'audio', 'source'
+          when 'audio', 'source'
             ArticleRules::Enclosure.from_media(element['src'], element['type'], base_url)
           when 'iframe'
             ArticleRules::Enclosure.from_iframe(element['src'], base_url)