html2rss 0.18.0 → 0.19.1

data/lib/html2rss/auto_source/scraper/wordpress_api/page_scope.rb

@@ -7,9 +7,16 @@ module Html2rss
         ##
         # Determines whether a WordPress page can safely be mapped to a posts query.
         class PageScope
+          # Canonical path segment for category archives.
           CATEGORY_SEGMENT = 'category'
+          # Canonical path segment for tag archives.
           TAG_SEGMENT = 'tag'
+          # Canonical path segment for author archives.
           AUTHOR_SEGMENT = 'author'
+          # Canonical path segment for paginated archives.
+          PAGE_SEGMENT = 'page'
+          # Canonical query key used for paginated archives.
+          PAGED_QUERY_KEY = 'paged'
 
           ##
           # @param parsed_body [Nokogiri::HTML::Document] parsed HTML document
@@ -20,7 +27,7 @@ module Html2rss
           end
 
           ##
-          # @param query [Hash<String, String>] scoped query params for the posts endpoint
+          # @param query [Hash{String => String}] scoped query params for the posts endpoint
           # @param fetchable [Boolean] whether a posts follow-up is safe for this page
           # @param reason [Symbol] classification of the resolved page scope
           def initialize(query:, fetchable:, reason:)
@@ -31,7 +38,7 @@ module Html2rss
           end
 
           ##
-          # @return [Hash<String, String>] query params to apply to the posts request
+          # @return [Hash{String => String}] query params to apply to the posts request
           attr_reader :query
 
           ##
@@ -58,11 +65,13 @@ module Html2rss
             ##
             # @return [PageScope] derived page scope
             def call
-              category_scope ||
-                tag_scope ||
-                author_scope ||
-                date_scope ||
-                fallback_scope
+              scope = category_scope ||
+                      tag_scope ||
+                      author_scope ||
+                      date_scope ||
+                      fallback_scope
+
+              apply_pagination(scope)
             end
 
             private
@@ -103,6 +112,17 @@ module Html2rss
               PageScope.new(query: {}, fetchable: true, reason: :unscoped)
             end
 
+            def apply_pagination(scope)
+              page = archive_page_number
+              return scope unless scope.fetchable? && page
+
+              PageScope.new(
+                query: scope.query.merge('page' => page.to_s),
+                fetchable: scope.fetchable?,
+                reason: scope.reason
+              )
+            end
+
             def scoped_scope(query)
               return unknown_archive_scope if query.values.any?(&:nil?)
 
@@ -166,8 +186,12 @@ module Html2rss
               @path_segments ||= canonical_or_current_url.path_segments
             end
 
+            def scoped_path_segments
+              @scoped_path_segments ||= paginated_path? ? path_segments[0...-2] : path_segments
+            end
+
             def leading_path_segment
-              path_segments.first
+              scoped_path_segments.first
             end
 
             def date_archive_path?
@@ -202,16 +226,33 @@ module Html2rss
             end
 
             def date_archive_segments
-              year_index = path_segments.find_index { _1.match?(/\A\d{4}\z/) }
+              year_index = scoped_path_segments.find_index { _1.match?(/\A\d{4}\z/) }
               return unless year_index
 
-              segments = path_segments.drop(year_index)
+              segments = scoped_path_segments.drop(year_index)
               return unless segments.length.between?(1, 3)
               return unless archive_segment_shape?(segments)
 
               segments
             end
 
+            def paginated_path?
+              return false if path_segments.length < 2
+              return false unless path_segments[-2] == PAGE_SEGMENT
+
+              !parse_positive_integer(path_segments[-1]).nil?
+            end
+
+            def archive_page_number
+              parse_positive_integer(canonical_or_current_url.query_values[PAGED_QUERY_KEY]) || path_page_number
+            end
+
+            def path_page_number
+              return unless paginated_path?
+
+              parse_positive_integer(path_segments[-1])
+            end
+
             def archive_segment_shape?(segments)
               month = segments[1]
               day = segments[2]
@@ -253,6 +294,15 @@ module Html2rss
 
               number
             end
+
+            def parse_positive_integer(value)
+              return nil unless value.to_s.match?(/\A\d+\z/)
+
+              number = value.to_i
+              return nil if number < 1
+
+              number
+            end
           end
         end
       end

data/lib/html2rss/auto_source/scraper/wordpress_api/posts_endpoint.rb

@@ -7,13 +7,14 @@ module Html2rss
         ##
         # Resolves the WordPress posts endpoint for a given page and scope.
         class PostsEndpoint
+          # REST API collection path for posts resources.
           POSTS_PATH = 'wp/v2/posts'
 
           ##
           # @param parsed_body [Nokogiri::HTML::Document] parsed HTML document
           # @param page_url [Html2rss::Url] canonical page URL
           # @param page_scope [Html2rss::AutoSource::Scraper::WordpressApi::PageScope] derived page scope
-          # @param posts_query [Hash<String, String>] query params for the posts request
+          # @param posts_query [Hash{String => String}] query params for the posts request
           # @param logger [Logger] logger used for operational warnings
           # @return [Html2rss::Url, nil] resolved posts endpoint or nil when unavailable
           def self.resolve(parsed_body:, page_url:, page_scope:, posts_query:, logger: Html2rss::Log)
@@ -24,7 +25,7 @@ module Html2rss
           # @param parsed_body [Nokogiri::HTML::Document] parsed HTML document
           # @param page_url [Html2rss::Url] canonical page URL
           # @param page_scope [Html2rss::AutoSource::Scraper::WordpressApi::PageScope] derived page scope
-          # @param posts_query [Hash<String, String>] query params for the posts request
+          # @param posts_query [Hash{String => String}] query params for the posts request
           # @param logger [Logger] logger used for operational warnings
           def initialize(parsed_body:, page_url:, page_scope:, posts_query:, logger:)
             @parsed_body = parsed_body

data/lib/html2rss/auto_source/scraper/wordpress_api.rb

@@ -10,9 +10,18 @@ module Html2rss
       class WordpressApi # rubocop:disable Metrics/ClassLength
         include Enumerable
 
+        # Selector for WordPress API discovery link tags.
         API_LINK_SELECTOR = 'link[rel="https://api.w.org/"][href]'
+        # Selector for canonical link tags used for scope normalization.
         CANONICAL_LINK_SELECTOR = 'link[rel="canonical"][href]'
+        # Fields requested from the WordPress posts endpoint.
         POSTS_FIELDS = %w[id title excerpt content link date categories].freeze
+        # Baseline query sent to WordPress posts API follow-ups.
+        POSTS_QUERY_DEFAULTS = {
+          '_fields' => POSTS_FIELDS.join(','),
+          'per_page' => '100'
+        }.freeze
+        # @return [Symbol] scraper config key
         def self.options_key = :wordpress_api
 
         ##
@@ -29,6 +38,7 @@ module Html2rss
         # @param url [String, Html2rss::Url] canonical page URL
         # @param request_session [Html2rss::RequestSession, nil] shared request session for follow-up fetches
         # @param _opts [Hash] unused scraper-specific options
+        # @option _opts [Object] :_reserved reserved for future scraper-specific options
         # @return [void]
         def initialize(parsed_body, url:, request_session: nil, **_opts)
           @parsed_body = parsed_body
@@ -40,7 +50,7 @@ module Html2rss
         ##
         # Yields article hashes from the WordPress posts API.
         #
-        # @yieldparam article [Hash<Symbol, Object>] normalized article hash
+        # @yieldparam article [Hash{Symbol => Object}] normalized article hash
         # @return [Enumerator, void] enumerator when no block is given
         def each
           return enum_for(:each) unless block_given?
@@ -94,7 +104,7 @@ module Html2rss
         end
 
         def article_id(_post, article_url)
-          root_path_query_id(article_url) || string(article_url.path) || article_url.to_s
+          root_path_query_id(article_url) || present_string(article_url.path) || article_url.to_s
         end
 
         def article_title(post)
@@ -106,11 +116,11 @@ module Html2rss
         end
 
         def article_published_at(post)
-          string(post[:date])
+          present_string(post[:date])
         end
 
         def article_categories(post)
-          Array(post[:categories]).filter_map { |value| string(value) }
+          Array(post[:categories]).filter_map { |value| present_string(value) }
         end
 
         def article_attributes(post, article_url)
@@ -125,7 +135,7 @@ module Html2rss
         end
 
         def absolute_link(link)
-          value = string(link)
+          value = present_string(link)
           return unless value
 
           Html2rss::Url.from_relative(value, url)
@@ -138,17 +148,17 @@ module Html2rss
         end
 
         def rendered_html(value)
-          text = string(value)
+          text = present_string(value)
           text unless text.nil?
         end
 
-        def string(value)
+        def present_string(value)
           text = value.to_s.strip
           text unless text.empty?
         end
 
         def root_path_query_id(article_url)
-          query = string(article_url.query)
+          query = present_string(article_url.query)
           return unless query
 
           path = article_url.path.to_s
@@ -158,10 +168,7 @@ module Html2rss
         end
 
         def posts_query
-          {
-            '_fields' => POSTS_FIELDS.join(','),
-            'per_page' => '100'
-          }.merge(page_scope.query)
+          POSTS_QUERY_DEFAULTS.merge(page_scope.query).transform_values(&:to_s)
         end
 
         def posts_endpoint_url

data/lib/html2rss/auto_source/scraper.rb

@@ -14,12 +14,15 @@ module Html2rss
     # Scrapers run in parallel threads, so implementations must avoid shared
     # mutable state and degrade by returning no articles when a follow-up would
     # be unsafe or unsupported.
-    #
     module Scraper
+      # Root markers indicating likely app-shell/client-rendered surfaces.
       APP_SHELL_ROOT_SELECTORS = '#app, #root, #__next, [data-reactroot], [ng-app], [id*="app-shell"]'
+      # Maximum anchors tolerated before app-shell detection is considered unlikely.
       APP_SHELL_MAX_ANCHORS = 2
+      # Maximum visible text length tolerated for app-shell classification.
       APP_SHELL_MAX_VISIBLE_TEXT_LENGTH = 220
 
+      # Ordered scraper classes considered during auto-source extraction.
       SCRAPERS = [
         WordpressApi,
         Schema,
@@ -32,6 +35,7 @@ module Html2rss
       ##
       # Error raised when no suitable scraper is found.
       class NoScraperFound < Html2rss::Error
+        # User-facing messages grouped by no-scraper surface category.
         CATEGORY_MESSAGES = {
           blocked_surface: 'No scrapers found: blocked surface likely (anti-bot or interstitial). ' \
                            'Retry with --strategy browserless, try a more specific public listing URL, ' \
@@ -44,6 +48,8 @@ module Html2rss
                                'or use explicit selectors in a feed config.'
         }.freeze
 
+        # @param message [String, nil] custom error message override
+        # @param category [Symbol] no-scraper classification
         def initialize(message = nil, category: :unsupported_surface)
           validate_category!(category)
           @category = category
@@ -66,6 +72,12 @@ module Html2rss
       # Returns an array of scraper classes that claim to find articles in the parsed body.
       # @param parsed_body [Nokogiri::HTML::Document] The parsed HTML body.
       # @param opts [Hash] The options hash.
+      # @option opts [Hash] :wordpress_api scraper toggle and configuration
+      # @option opts [Hash] :schema scraper toggle and configuration
+      # @option opts [Hash] :microdata scraper toggle and configuration
+      # @option opts [Hash] :json_state scraper toggle and configuration
+      # @option opts [Hash] :semantic_html scraper toggle and configuration
+      # @option opts [Hash] :html scraper toggle and configuration
       # @return [Array<Class>] An array of scraper classes that can handle the parsed body.
       def self.from(parsed_body, opts = Html2rss::AutoSource::DEFAULT_CONFIG[:scraper])
         scrapers = SCRAPERS.select { |scraper| opts.dig(scraper.options_key, :enabled) }
@@ -81,6 +93,12 @@ module Html2rss
       # @param url [String, Html2rss::Url] The page url.
       # @param request_session [Html2rss::RequestSession, nil] Shared follow-up session.
       # @param opts [Hash] The options hash.
+      # @option opts [Hash] :wordpress_api scraper toggle and configuration
+      # @option opts [Hash] :schema scraper toggle and configuration
+      # @option opts [Hash] :microdata scraper toggle and configuration
+      # @option opts [Hash] :json_state scraper toggle and configuration
+      # @option opts [Hash] :semantic_html scraper toggle and configuration
+      # @option opts [Hash] :html scraper toggle and configuration
       # @return [Array<Object>] An array of scraper instances that can handle the parsed body.
       #
       # `instances_for` is the main entrypoint for extraction. It lets a scraper

data/lib/html2rss/auto_source.rb

@@ -17,6 +17,7 @@ module Html2rss
   # @see Html2rss::AutoSource::Scraper::SemanticHtml
   # @see Html2rss::AutoSource::Scraper::Html
   class AutoSource
+    # Default auto-source configuration shipped for scraper and cleanup behavior.
     DEFAULT_CONFIG = {
       scraper: {
         wordpress_api: {
@@ -67,6 +68,7 @@ module Html2rss
     end.freeze
     private_constant :SCRAPER_CONFIG
 
+    # Runtime schema used to validate auto-source config values.
     Config = Dry::Schema.Params do
       optional(:scraper).hash(&SCRAPER_CONFIG)
 
@@ -80,6 +82,8 @@ module Html2rss
     # @param response [Html2rss::RequestService::Response] initial page response
     # @param opts [Hash] validated auto-source options
     # @param request_session [Html2rss::RequestSession, nil] shared request session for follow-up fetches
+    # @option opts [Hash] :scraper scraper configuration map
+    # @option opts [Hash] :cleanup cleanup configuration map
     # @return [void]
     def initialize(response, opts = DEFAULT_CONFIG, request_session: nil)
       @parsed_body = response.parsed_body

data/lib/html2rss/blocked_surface.rb

@@ -7,6 +7,7 @@ module Html2rss
   # This module centralizes signature matching so request-time guards and
   # auto-source surface classification stay consistent.
   module BlockedSurface
+    # Known interstitial fingerprints used to detect blocked or anti-bot surfaces.
     INTERSTITIAL_SIGNATURES = [
       {
         key: :cloudflare_interstitial,

data/lib/html2rss/category_extractor.rb

@@ -49,7 +49,7 @@ module Html2rss
     ##
     # Extracts categories from data attributes of a single element.
     #
-    # @param element [Nokogiri::XML::Element] The element to process
+    # @param element [Nokogiri::XML::Element] metadata element that may contain category links
     # @return [Set<String>] Set of category strings
     def self.extract_element_data_categories(element)
       Set.new.tap do |categories|
@@ -65,7 +65,7 @@ module Html2rss
     ##
     # Extracts text-based categories from elements, splitting content into discrete values.
     #
-    # @param element [Nokogiri::XML::Element] The element to process
+    # @param element [Nokogiri::XML::Element] metadata element whose text may contain delimiters
     # @return [Set<String>] Set of category strings
     def self.extract_text_categories(element)
       anchor_values = element.css('a').filter_map do |node|

data/lib/html2rss/cli.rb

@@ -11,7 +11,23 @@ module Html2rss
   # The Html2rss command line interface.
   class CLI < Thor # rubocop:disable Metrics/ClassLength
     check_unknown_options!
+    # Ordered fallback chain attempted by auto strategy.
+    #
+    # @return [Array<Symbol>]
+    AUTO_FALLBACK_CHAIN = Html2rss::FeedPipeline::AutoFallback::CHAIN.freeze
+    # Supported CLI strategy option values.
+    #
+    # @return [Array<String>]
+    STRATEGY_OPTION_ENUM = (['auto'] + Html2rss::RequestService.strategy_names).uniq.freeze
+    # User-facing strategy help text that reflects the current fallback chain.
+    #
+    # @return [String]
+    STRATEGY_OPTION_DESC = [
+      'Optional request strategy (defaults to auto; auto tries',
+      "#{AUTO_FALLBACK_CHAIN.join(' -> ')})"
+    ].join(' ').freeze
 
+    # @return [Boolean] whether Thor should terminate process on command failures
     def self.exit_on_failure?
       true
     end
@@ -24,14 +40,17 @@ module Html2rss
                   default: {}
     method_option :strategy,
                   type: :string,
-                  desc: 'The strategy to request the URL',
-                  enum: %w[faraday browserless]
+                  desc: STRATEGY_OPTION_DESC,
+                  enum: STRATEGY_OPTION_ENUM
     method_option :max_redirects,
                   type: :numeric,
                   desc: 'Maximum redirects to follow per request'
     method_option :max_requests,
                   type: :numeric,
                   desc: 'Maximum requests to allow for this feed build'
+    # @param yaml_file [String] path to YAML config
+    # @param feed_name [String, nil] optional named feed in multi-feed config
+    # @return [void]
     def feed(yaml_file, feed_name = nil)
       config = Html2rss.config_from_yaml_file(yaml_file, feed_name)
       config[:params] = options[:params] || {}
@@ -43,8 +62,8 @@ module Html2rss
     desc 'auto [URL]', 'Automatically sources an RSS feed from the URL'
     method_option :strategy,
                   type: :string,
-                  desc: 'The strategy to request the URL',
-                  enum: %w[faraday browserless]
+                  desc: STRATEGY_OPTION_DESC,
+                  enum: STRATEGY_OPTION_ENUM
     method_option :format,
                   type: :string,
                   desc: 'Output format for the auto-sourced feed',
@@ -57,6 +76,8 @@ module Html2rss
     method_option :max_requests,
                   type: :numeric,
                   desc: 'Maximum requests to allow for this feed build'
+    # @param url [String] source page URL for auto discovery
+    # @return [void]
     def auto(url) # rubocop:disable Metrics/MethodLength
       format = options.fetch(:format, 'rss')
       source_method = format == 'jsonfeed' ? Html2rss.method(:auto_json_feed) : Html2rss.method(:auto_source)
@@ -156,7 +177,7 @@ module Html2rss
     end
 
     def current_strategy
-      options[:strategy]&.to_sym || :faraday
+      options[:strategy]&.to_sym || :auto
     end
 
     def current_max_redirects
@@ -186,7 +207,10 @@ module Html2rss
             'or increase request.max_requests in the config.'
     rescue Html2rss::RequestService::BrowserlessConfigurationError,
            Html2rss::RequestService::BrowserlessConnectionFailed,
-           Html2rss::RequestService::BlockedSurfaceDetected => error
+           Html2rss::RequestService::BotasaurusConfigurationError,
+           Html2rss::RequestService::BotasaurusConnectionFailed,
+           Html2rss::RequestService::BlockedSurfaceDetected,
+           Html2rss::NoFeedItemsExtracted => error
       raise Thor::Error, error.message
     end
   end

data/lib/html2rss/config/class_methods.rb

@@ -5,12 +5,13 @@ module Html2rss
     ##
     # Public class-level helpers for loading, validating, and exporting config.
     module ClassMethods
+      # Sentinel to differentiate omitted params from explicit `nil`.
       UNSET = Object.new.freeze
 
       ##
       # Returns the exported JSON Schema for html2rss configuration.
       #
-      # @return [Hash<String, Object>] JSON Schema represented as a Ruby hash
+      # @return [Hash{String => Object}] JSON Schema represented as a Ruby hash
       def json_schema
         Schema.json_schema
       end
@@ -27,15 +28,15 @@ module Html2rss
       ##
       # Validates a configuration hash with the runtime validator.
       #
-      # @param config [Hash<Symbol, Object>] the configuration hash
-      # @param params [Hash<Symbol, Object>, Hash<String, Object>, nil] dynamic parameters for string formatting
+      # @param config [Hash{Symbol => Object}] the configuration hash
+      # @param params [Hash{Symbol => Object}, Hash{String => Object}, nil] dynamic parameters for string formatting
       # @return [Dry::Validation::Result] validation result after defaults and deprecations are applied
       def validate(config, params: UNSET)
         prepared_config = prepare_for_validation(resolve_effective_config(config, params:))
 
         Validator.new.call(prepared_config)
       rescue DynamicParams::ParamsMissing => error
-        prepared_config = prepare_for_validation(deep_dup(config))
+        prepared_config = prepare_for_validation(HashUtil.deep_symbolize_keys(config, context: 'config'))
         prepared_config[:dynamic_params_error] = error.message
 
         Validator.new.call(prepared_config)
@@ -55,7 +56,7 @@ module Html2rss
       # @param file [String] the YAML file to load
       # @param feed_name [String, nil] optional feed name for multi-feed files
       # @param multiple_feeds_key [Symbol] key under which multiple feeds are defined
-      # @param params [Hash<Symbol, Object>, Hash<String, Object>, nil] dynamic parameters for string formatting
+      # @param params [Hash{Symbol => Object}, Hash{String => Object}, nil] dynamic parameters for string formatting
       # @return [Dry::Validation::Result] validation result after defaults and deprecations are applied
       def validate_yaml(file, feed_name = nil, multiple_feeds_key: MultipleFeedsConfig::CONFIG_KEY_FEEDS, params: UNSET)
         validate(load_yaml(file, feed_name, multiple_feeds_key:), params:)
@@ -69,7 +70,7 @@ module Html2rss
       # @param file [String] the YAML file to load.
       # @param feed_name [String, nil] the feed name when using multiple feeds.
       # @param multiple_feeds_key [Symbol] the key under which multiple feeds are defined.
-      # @return [Hash<Symbol, Object>] the configuration hash.
+      # @return [Hash{Symbol => Object}] the configuration hash.
       # @raise [ArgumentError] if the file doesn't exist or feed is not found.
       # rubocop:disable Metrics/MethodLength
       def load_yaml(file, feed_name = nil, multiple_feeds_key: MultipleFeedsConfig::CONFIG_KEY_FEEDS)
@@ -97,8 +98,8 @@ module Html2rss
       # Processes the provided configuration hash, applying dynamic parameters if given,
       # and returns a new configuration object.
       #
-      # @param config [Hash<Symbol, Object>] the configuration hash.
-      # @param params [Hash<Symbol, Object>, Hash<String, Object>, nil] dynamic parameters for string formatting.
+      # @param config [Hash{Symbol => Object}] the configuration hash.
+      # @param params [Hash{Symbol => Object}, Hash{String => Object}, nil] dynamic parameters for string formatting.
       # @return [Html2rss::Config] the configuration object.
       def from_hash(config, params: UNSET)
         new(resolve_effective_config(config, params:))
@@ -110,7 +111,7 @@ module Html2rss
       # @param url [String] source page URL
       # @param items_selector [String, nil] optional selector hint for item extraction
       # @param request_controls [Html2rss::RequestControls, nil] explicit request controls to write
-      # @return [Hash<Symbol, Object>] feed config hash ready for {from_hash}
+      # @return [Hash{Symbol => Object}] feed config hash ready for {from_hash}
       def auto_source_config(url:, items_selector: nil, request_controls: nil)
         config = {
           channel: default_config[:channel].merge(url:),
@@ -127,10 +128,10 @@ module Html2rss
       ##
       # Provides a default configuration.
       #
-      # @return [Hash<Symbol, Object>] a hash with default configuration values.
+      # @return [Hash{Symbol => Object}] a hash with default configuration values.
       def default_config
         {
-          strategy: RequestService.default_strategy_name,
+          strategy: default_strategy_name,
           request: {
             max_redirects: RequestService::Policy::DEFAULTS[:max_redirects],
             max_requests: RequestService::Policy::DEFAULTS[:max_requests]
@@ -141,15 +142,22 @@ module Html2rss
         }
       end
 
+      # @return [Symbol] the default strategy for feed orchestration
+      def default_strategy_name
+        :auto
+      end
+
       private
 
       def resolve_effective_config(config, params:)
-        effective_config = deep_dup(config)
+        effective_config = HashUtil.deep_symbolize_keys(config, context: 'config')
         resolved_params = parameter_defaults(effective_config)
-        resolved_params.merge!(params) unless params.equal?(UNSET) || params.nil?
+        unless params.equal?(UNSET) || params.nil?
+          resolved_params.merge!(HashUtil.deep_symbolize_keys(params, context: 'params'))
+        end
 
-        DynamicParams.call(effective_config[:headers], resolved_params)
-        DynamicParams.call(effective_config[:channel], resolved_params)
+        effective_config[:headers] = DynamicParams.call(effective_config[:headers], resolved_params)
+        effective_config[:channel] = DynamicParams.call(effective_config[:channel], resolved_params)
 
         effective_config
       end
@@ -163,27 +171,8 @@ module Html2rss
       end
 
       def prepare_for_validation(config)
-        Config::Preparer.new.call(deep_dup(config))
-      end
-
-      # rubocop:disable Metrics/MethodLength
-      def deep_dup(object)
-        case object
-        when Hash
-          object.transform_values do |value|
-            deep_dup(value)
-          end
-        when Array
-          object.map { |value| deep_dup(value) }
-        else
-          begin
-            object.dup
-          rescue TypeError
-            object
-          end
-        end
+        Config::Preparer.new.call(HashUtil.deep_dup(config))
       end
-      # rubocop:enable Metrics/MethodLength
     end
   end
 end

data/lib/html2rss/config/dynamic_params.rb

@@ -4,13 +4,14 @@ module Html2rss
   class Config
     # Processes and applies dynamic parameter formatting in configuration values.
     class DynamicParams
+      # Raised when string interpolation references an unavailable parameter.
       class ParamsMissing < Html2rss::Error; end
 
       class << self
         # Recursively traverses the given value and formats any strings containing
         # placeholders with values from the provided params.
         #
-        # @param value [String, Hash, Enumerable, Object] The value to process.
+        # @param value [String, Hash, Enumerable, Object] value that may contain parameter placeholders
         # @param params [Hash] The parameters for substitution.
         # @param getter [Proc, nil] Optional proc to retrieve a key's value.
         # @param replace_missing_with [Object, nil] Value to substitute if a key is missing.
@@ -55,12 +56,13 @@ module Html2rss
         end
 
         def from_hash(hash, params, getter:, replace_missing_with:)
-          hash.transform_keys!(&:to_sym)
-          hash.transform_values! { |value| call(value, params, getter:, replace_missing_with:) }
+          HashUtil.deep_symbolize_keys(hash, context: 'dynamic params hash').to_h do |key, value|
+            [key, call(value, params, getter:, replace_missing_with:)]
+          end
         end
 
         def from_enumerable(enumerable, params, getter:, replace_missing_with:)
-          enumerable.map! { |value| call(value, params, getter:, replace_missing_with:) }
+          enumerable.map { |value| call(value, params, getter:, replace_missing_with:) }
         end
       end
     end

data/lib/html2rss/config/multiple_feeds_config.rb

@@ -7,6 +7,7 @@ module Html2rss
     # where each feed name is the key for its feed configuration.
     # All global configuration keys (outside :feeds) are merged into each feed's settings.
     class MultipleFeedsConfig
+      # Reserved YAML key under which multiple named feed configs are defined.
       CONFIG_KEY_FEEDS = :feeds
 
       class << self
@@ -37,11 +38,11 @@ module Html2rss
           local_value = config[key]
           case local_value
           when Hash
-            global_value.is_a?(Hash) ? global_value.merge(local_value) : local_value
+            global_value.is_a?(Hash) ? HashUtil.deep_merge(global_value, local_value) : local_value
           when Array
             global_value.is_a?(Array) ? global_value + local_value : local_value
           else
-            global_value
+            local_value.nil? ? global_value : local_value
           end
         end
       end