html2rss 0.22.2 → 0.24.0

data/lib/html2rss/config/schema.rb

@@ -3,7 +3,7 @@
 module Html2rss
   class Config
     ##
-    # Builds the exported configuration JSON Schema from the runtime validators.
+    # JSON export adapter from the runtime validators to the packaged schema artifact.
     module Schema
       module_function
 
@@ -60,7 +60,8 @@ module Html2rss
         def call
           schema = validator_schema
           apply_top_level(schema)
-          assign_properties(schema.fetch(:properties))
+          schema.fetch(:properties).merge!(overlay)
+          schema.fetch(:properties).delete(:dynamic_params_error)
           DeepStringifier.call(schema)
         end
 
@@ -78,124 +79,74 @@ module Html2rss
           ]
         end
 
-        def assign_properties(properties)
-          properties.merge!(
-            strategy: Components.strategy,
-            headers: Components.headers,
-            stylesheets: Components.stylesheets,
-            auto_source: Components.auto_source,
-            selectors: Components.selectors
-          )
-          properties.delete(:dynamic_params_error)
-        end
-      end
-
-      ##
-      # Exposes schema fragments that populate the top-level configuration schema.
-      module Components
-        module_function
-
-        # @return [Hash{Symbol => Object}] schema fragment for strategy selection
-        def strategy
-          {
-            type: 'string',
-            not: { type: 'null' }
-          }
-        end
-
-        # @return [Hash{Symbol => Object}] schema fragment for headers
-        def headers
-          {
-            type: 'object',
-            description: 'HTTP headers applied to every request.',
-            additionalProperties: { type: 'string' }
-          }
-        end
-
-        # @return [Hash{Symbol => Object}] schema fragment for stylesheet definitions
-        def stylesheets
-          {
-            type: 'array',
-            description: 'Collection of stylesheets to attach to the RSS feed.',
-            items: Html2rss::Config::Validator::StylesheetConfig.json_schema(loose: true)
-          }
-        end
-
-        # @return [Hash{Symbol => Object}] schema fragment for auto_source configuration
-        def auto_source
-          schema = Html2rss::AutoSource::Config.json_schema(loose: true)
-          schema[:default] = DeepStringifier.call(Html2rss::AutoSource::DEFAULT_CONFIG)
-          schema
-        end
-
-        # @return [Hash{Symbol => Object}] schema fragment for selectors configuration
-        def selectors
-          Selectors.schema
-        end
-      end
-
-      ##
-      # Provides schema fragments that document selector configuration.
-      module Selectors
-        module_function
-
-        # Pattern used for dynamic selector keys excluding reserved selector names.
-        RESERVED_SELECTOR_PATTERN = '^(?!items$|enclosure$|guid$|categories$).+$'
-
-        # @return [Hash{Symbol => Object}] schema fragment for selectors root object
-        def schema
-          {
-            type: 'object',
-            description: 'Selectors used to extract article attributes.',
-            properties: selector_properties,
-            patternProperties: pattern_properties,
-            additionalProperties: true
+        # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Layout/LineLength
+        def overlay
+          items_schema = Html2rss::Config::SelectorsValidator::Items.new.schema.json_schema(loose: true)
+          items_schema[:properties][:pagination] = {
+            description: 'Pagination configuration or maximum page count integer.',
+            oneOf: [
+              { type: 'integer', exclusiveMinimum: 0 },
+              {
+                type: 'object',
+                properties: {
+                  strategy: { type: 'string', enum: Html2rss::RequestSession::Pager.strategy_names },
+                  max_pages: { type: 'integer', exclusiveMinimum: 0 },
+                  selector: { type: 'string' },
+                  param: { type: 'string' },
+                  start_page: { type: 'integer' },
+                  step: { type: 'integer', exclusiveMinimum: 0 },
+                  start_offset: { type: 'integer' },
+                  increment: { type: 'integer', exclusiveMinimum: 0 },
+                  cursor_path: { type: 'string' },
+                  next_url_path: { type: 'string' }
+                },
+                additionalProperties: true
+              }
+            ]
           }
-        end
 
-        # rubocop:disable Layout/LineLength
-        # @return [Hash{Symbol => Object}] schema map for reserved selector properties
-        def selector_properties
           {
-            items: items_schema,
-            enclosure: enclosure_schema,
-            guid: reference_array('List of selector keys used to build the GUID. Each entry must reference a sibling selector key; runtime validation enforces those references.'),
-            categories: reference_array('List of selector keys whose values will be used as categories. Each entry must reference a sibling selector key; runtime validation enforces those references.')
+            strategy: {
+              type: 'string',
+              not: { type: 'null' }
+            },
+            headers: {
+              type: 'object',
+              description: 'HTTP headers applied to every request.',
+              additionalProperties: { type: 'string' }
+            },
+            stylesheets: {
+              type: 'array',
+              description: 'Collection of stylesheets to attach to the RSS feed.',
+              items: Html2rss::Config::Validator::StylesheetConfig.json_schema(loose: true)
+            },
+            auto_source: Html2rss::Config::AutoSourceContract.json_schema(loose: true).merge(
+              default: DeepStringifier.call(Html2rss::AutoSource::DEFAULT_CONFIG)
+            ),
+            selectors: {
+              type: 'object',
+              description: 'Selectors used to extract article attributes.',
+              properties: {
+                items: items_schema.merge(
+                  description: 'Defines the items selector and optional enhancement settings.'
+                ),
+                enclosure: Html2rss::Config::SelectorsValidator::Enclosure.new.schema.json_schema(loose: true).merge(
+                  description: 'Describes enclosure extraction settings.'
+                ),
+                guid: reference_array('List of selector keys used to build the GUID. Each entry must reference a sibling selector key; runtime validation enforces those references.'),
+                categories: reference_array('List of selector keys whose values will be used as categories. Each entry must reference a sibling selector key; runtime validation enforces those references.')
+              },
+              patternProperties: {
+                '^(?!items$|enclosure$|guid$|categories$).+$' => Html2rss::Config::SelectorsValidator::Selector.new.schema.json_schema(loose: true).merge(
+                  description: 'Dynamic selector definition keyed by attribute name.'
+                )
+              },
+              additionalProperties: true
+            }
           }
         end
-        # rubocop:enable Layout/LineLength
-
-        # @return [Hash{String => Object}] schema map for dynamic selector keys
-        def pattern_properties
-          { RESERVED_SELECTOR_PATTERN => dynamic_selector_schema }
-        end
-
-        # @return [Hash{Symbol => Object}] schema fragment for dynamic selector entries
-        def dynamic_selector_schema
-          Html2rss::Selectors::Config::Selector.new.schema.json_schema(loose: true).merge(
-            description: 'Dynamic selector definition keyed by attribute name.'
-          )
-        end
-
-        # @return [Hash{Symbol => Object}] schema fragment for `items` selector configuration
-        def items_schema
-          Html2rss::Selectors::Config::Items.new.schema.json_schema(loose: true).merge(
-            description: 'Defines the items selector and optional enhancement settings.'
-          )
-        end
-
-        # @return [Hash{Symbol => Object}] schema fragment for `enclosure` selector configuration
-        def enclosure_schema
-          Html2rss::Selectors::Config::Enclosure.new.schema.json_schema(loose: true).merge(
-            description: 'Describes enclosure extraction settings.'
-          )
-        end
+        # rubocop:enable Metrics/MethodLength, Metrics/AbcSize, Layout/LineLength
 
-        # JSON Schema can enforce non-empty reference arrays, while runtime
-        # validation remains authoritative for checking that each entry points
-        # to an existing sibling selector key.
-        # @param description [String] human-readable description for the reference field
-        # @return [Hash{Symbol => Object}] JSON schema fragment for selector references
         def reference_array(description)
           {
             type: 'array',

data/lib/html2rss/{selectors/config.rb → config/selectors_validator.rb}

@@ -3,23 +3,72 @@
 require 'dry-validation'
 
 module Html2rss
-  class Selectors
+  class Config
     ##
     # Validates the configuration hash for :selectors.
-    class Config < Dry::Validation::Contract
+    class SelectorsValidator < Dry::Validation::Contract
       # Required wrapper key used to validate dynamic selector names.
       NESTING_KEY = :dynamic_keys_workaround
 
       ##
       # Validates the configuration of the :items selector
       class Items < Dry::Validation::Contract
+        # Supported pagination strategy names (sole source: RequestSession::Pager).
+        # @return [Array<String>]
+        STRATEGY_NAMES = Html2rss::RequestSession::Pager.strategy_names
+
         params do
           required(:selector).filled(:string)
           optional(:order).filled(included_in?: %w[reverse])
           optional(:enhance).filled(:bool?)
-          optional(:pagination).hash do
-            required(:max_pages).filled(:integer, gt?: 0)
+          optional(:pagination)
+        end
+
+        rule(:pagination) do
+          next if value.nil?
+
+          if value.is_a?(Integer)
+            key.failure('integer must be greater than 0') if value <= 0
+          elsif value.is_a?(Hash)
+            val_hash = value.transform_keys(&:to_sym)
+            validate_pagination_hash(val_hash, key)
+          else
+            key.failure('must be an integer or a hash')
+          end
+        end
+
+        private
+
+        def validate_pagination_hash(val_hash, key)
+          # Fail loud on explicit nil/non-positive: truthy checks would silently accept max_pages: nil.
+          if val_hash.key?(:max_pages) && (!val_hash[:max_pages].is_a?(Integer) || val_hash[:max_pages] <= 0)
+            key.failure('`max_pages` must be an integer greater than 0')
+          end
+
+          strategy = (val_hash[:strategy] || 'rel_next').to_s
+          unless STRATEGY_NAMES.include?(strategy)
+            key.failure("`strategy` must be one of: #{STRATEGY_NAMES.join(', ')}")
           end
+
+          validate_strategy_fields(strategy, val_hash, key)
+        end
+
+        def validate_strategy_fields(strategy, val_hash, key)
+          validate_custom_selector(val_hash, key) if strategy == 'custom_selector'
+          validate_json_cursor(val_hash, key) if strategy == 'json_cursor'
+        end
+
+        def validate_custom_selector(val_hash, key)
+          return unless val_hash[:selector].nil? || val_hash[:selector].to_s.strip.empty?
+
+          key.failure('`custom_selector` strategy requires `selector` to be specified')
+        end
+
+        def validate_json_cursor(val_hash, key)
+          return unless (val_hash[:cursor_path].nil? || val_hash[:cursor_path].to_s.strip.empty?) &&
+                        (val_hash[:next_url_path].nil? || val_hash[:next_url_path].to_s.strip.empty?)
+
+          key.failure('`json_cursor` strategy requires either `cursor_path` or `next_url_path`')
         end
       end
 
@@ -84,9 +133,9 @@ module Html2rss
         value.each_pair do |selector_key, selector|
           case selector_key.to_sym
           when Selectors::ITEMS_SELECTOR_KEY
-            Items.new.call(selector).errors.each { |error| key(selector_key).failure(error) }
+            Items.new.call(selector).errors.each { |error| key(selector_key).failure(error.text) }
           when :enclosure
-            Enclosure.new.call(selector).errors.each { |error| key(selector_key).failure(error) }
+            Enclosure.new.call(selector).errors.each { |error| key(selector_key).failure(error.text) }
           when :guid, :categories
             unless selector.is_a?(Array)
               key(selector_key).failure("`#{selector_key}` must be an array")
@@ -102,7 +151,7 @@ module Html2rss
             end
           else
             # From here on, the selector is found under its "dynamic" selector_key
-            Selector.new.call(selector).errors.each { |error| key(selector_key).failure(error) }
+            Selector.new.call(selector).errors.each { |error| key(selector_key).failure(error.text) }
           end
         end
       end

data/lib/html2rss/config/validator.rb

@@ -10,11 +10,11 @@ module Html2rss
       # URI format used for channel URL validation.
       URI_REGEXP = Url::URI_REGEXP
       # Allowed stylesheet MIME types.
-      STYLESHEET_TYPES = RssBuilder::Stylesheet::TYPES
+      STYLESHEET_TYPES = FeedBuilder::Rss::Stylesheet::TYPES
       # Optional language/region format (`en` or `en-US`).
       LANGUAGE_FORMAT_REGEX = /\A[a-z]{2}(-[A-Z]{2})?\z/
-      # Baseline strategy enum exported in static schema artifacts.
-      BASE_STRATEGY_OPTIONS = ([:auto] + Html2rss::RequestService.strategy_names.map(&:to_sym)).uniq.freeze
+      # Baseline strategy-plan enum (:auto plus concrete RequestService strategies).
+      BASE_STRATEGY_OPTIONS = Html2rss::FeedPipeline::StrategyPlan.accepted_names.freeze
 
       # Contract for the top-level `channel` section.
       ChannelConfig = Dry::Schema.Params do
@@ -91,7 +91,7 @@ module Html2rss
         required(:channel).hash(ChannelConfig)
         optional(:headers).hash
         optional(:stylesheets).array(StylesheetConfig)
-        optional(:auto_source).hash(AutoSource::Config)
+        optional(:auto_source).hash(Config::AutoSourceContract)
         optional(:selectors).hash
         optional(:dynamic_params_error).maybe(:string)
         optional(:request).hash(RequestConfig)
@@ -111,7 +111,7 @@ module Html2rss
 
       rule(:strategy) do
         next if value.nil?
-        next if value == :auto || Html2rss::RequestService.strategy_registered?(value)
+        next if Html2rss::FeedPipeline::StrategyPlan.valid?(value)
 
         key.failure("must be one of: #{BASE_STRATEGY_OPTIONS.join(', ')}")
       end
@@ -126,7 +126,7 @@ module Html2rss
       rule(:selectors) do
         next unless value
 
-        errors = Html2rss::Selectors::Config.call(value).errors
+        errors = Config::SelectorsValidator.call(value).errors
         errors.each { |error| key(:selectors).failure(error.text) } unless errors.empty?
       end
 

data/lib/html2rss/config.rb

@@ -10,15 +10,186 @@ module Html2rss
   # supporting both single and multiple feed configurations.
   #
   # Configuration is validated during initialization.
-  class Config
+  class Config # rubocop:disable Metrics/ClassLength
     # Raised when a configuration hash fails runtime validation.
     class InvalidConfig < Html2rss::Error; end
-    extend ClassMethods
+    # Sentinel to differentiate omitted params from explicit `nil`.
+    UNSET = Object.new.freeze
+
+    class << self
+      ##
+      # Returns the exported JSON Schema for html2rss configuration.
+      #
+      # @return [Hash{String => Object}] JSON Schema represented as a Ruby hash
+      def json_schema
+        Schema.json_schema
+      end
+
+      ##
+      # Returns the exported JSON Schema as JSON.
+      #
+      # @param pretty [Boolean] whether to pretty-print the JSON output
+      # @return [String] serialized JSON Schema
+      def json_schema_json(pretty: true)
+        pretty ? JSON.pretty_generate(json_schema) : JSON.generate(json_schema)
+      end
+
+      ##
+      # 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
+      # @return [Dry::Validation::Result] validation result after defaults 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(HashUtil.deep_symbolize_keys(config, context: 'config'))
+        prepared_config[:dynamic_params_error] = error.message
+
+        Validator.new.call(prepared_config)
+      end
+
+      ##
+      # Returns the packaged JSON Schema file path.
+      #
+      # @return [String] absolute path to the packaged JSON Schema file
+      def schema_path
+        Schema.path
+      end
+
+      ##
+      # Loads and validates a YAML configuration file.
+      #
+      # @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
+      # @return [Dry::Validation::Result] validation result after defaults 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:)
+      end
+
+      ##
+      # Loads the feed configuration from a YAML file.
+      #
+      # Supports multiple feeds defined under the specified key (default :feeds).
+      #
+      # @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.
+      # @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)
+        raise ArgumentError, "File '#{file}' does not exist" unless File.exist?(file)
+        raise ArgumentError, "`#{multiple_feeds_key}` is a reserved feed name" if feed_name == multiple_feeds_key
+
+        yaml = YAML.safe_load_file(file, symbolize_names: true)
+
+        return yaml unless yaml.key?(multiple_feeds_key)
+
+        unless feed_name
+          available_feeds = yaml.fetch(multiple_feeds_key).keys.join(', ')
+          raise ArgumentError,
+                "Feed name is required under `#{multiple_feeds_key}`. Available feeds: #{available_feeds}"
+        end
+
+        config = yaml.dig(multiple_feeds_key, feed_name.to_sym)
+        raise ArgumentError, "Feed '#{feed_name}' not found under `#{multiple_feeds_key}` key." unless config
+
+        MultipleFeedsConfig.to_single_feed(config, yaml, multiple_feeds_key:)
+      end
+      # rubocop:enable Metrics/MethodLength
+
+      ##
+      # 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.
+      # @return [Html2rss::Config] the configuration object.
+      def from_hash(config, params: UNSET)
+        new(resolve_effective_config(config, params:))
+      end
+
+      ##
+      # Builds a top-level auto-source feed config for the public shortcut APIs.
+      #
+      # @param url [String] source page URL
+      # @param items_selector [String, nil] optional selector hint for item extraction
+      # @param request_controls [Html2rss::Config::RequestControls, nil] explicit request controls to write
+      # @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:),
+          auto_source: AutoSource::DEFAULT_CONFIG
+        }
+
+        request_controls ||= RequestControls.new
+        request_controls.apply_to(config)
+
+        config[:selectors] = { items: { selector: items_selector, enhance: true } } if items_selector
+        config
+      end
+
+      ##
+      # Provides a default configuration.
+      #
+      # @return [Hash{Symbol => Object}] a hash with default configuration values.
+      def default_config
+        {
+          strategy: default_strategy_name,
+          request: default_request_config,
+          channel: { time_zone: 'UTC' },
+          headers: RequestHeaders.browser_defaults,
+          stylesheets: Html2rss.defaults.stylesheets || []
+        }
+      end
+
+      # @return [Symbol] the default feed-level strategy plan (+:auto+ or concrete)
+      def default_strategy_name
+        Html2rss.defaults.default_strategy || :auto
+      end
+
+      private
+
+      def default_request_config
+        {
+          max_redirects: RequestService::Policy::DEFAULTS[:max_redirects],
+          max_requests: RequestService::Policy::DEFAULTS[:max_requests],
+          total_timeout_seconds: RequestService::Policy::DEFAULTS[:total_timeout_seconds]
+        }
+      end
+
+      def resolve_effective_config(config, params:)
+        cfg = HashUtil.deep_symbolize_keys(config, context: 'config')
+        p = parameter_defaults(cfg)
+        p.merge!(HashUtil.deep_symbolize_keys(params, context: 'params')) unless params.equal?(UNSET) || params.nil?
+
+        cfg[:headers] = DynamicParams.call(cfg[:headers], p) if cfg[:headers]
+        cfg[:channel] = DynamicParams.call(cfg[:channel], p) if cfg[:channel]
+        cfg
+      end
+
+      def parameter_defaults(config)
+        config.fetch(:parameters, {})
+              .filter_map do |name, definition|
+                [name, definition[:default]] if definition.is_a?(Hash) && definition.key?(:default)
+              end
+              .to_h
+      end
+
+      def prepare_for_validation(config)
+        Config::Preparer.new.call(HashUtil.deep_dup(config))
+      end
+    end
 
     ##
     # Initializes the configuration object.
     #
-    # Processes deprecated attributes, applies default values, and validates the configuration.
+    # Applies default values and validates the configuration.
     #
     # @param config [Hash{Symbol => Object}] the configuration hash.
     # @raise [InvalidConfig] if the configuration fails validation.
@@ -54,7 +225,7 @@ module Html2rss
     end
 
     ##
-    # @return [Html2rss::RequestControls] request controls with provenance
+    # @return [Html2rss::Config::RequestControls] request controls with provenance
     attr_reader :request_controls
 
     # @return [Hash{String => String}] normalized HTTP headers
@@ -82,11 +253,10 @@ module Html2rss
     class Preparer
       ##
       # @param config [Hash{Symbol => Object}] raw config input
-      # @return [Hash{Symbol => Object}] config with defaults and deprecations applied
+      # @return [Hash{Symbol => Object}] config with defaults applied
       def call(config)
         config = config.dup if config.frozen?
 
-        config = handle_deprecated_channel_attributes(config)
         config = apply_default_config(config)
         config = apply_default_selectors_config(config) if config[:selectors]
         config = apply_default_auto_source_config(config) if config[:auto_source]
@@ -96,19 +266,6 @@ module Html2rss
 
       private
 
-      def handle_deprecated_channel_attributes(config)
-        { strategy: Config.default_strategy_name, headers: {} }.each_pair do |key, default_value|
-          if !config[key] && (value = config.dig(:channel, key))
-            Log.warn("The `channel.#{key}` key is deprecated. Please move the definition of `#{key}` to the top level.")
-            config[key] = value
-          end
-
-          config[key] ||= default_value
-        end
-
-        config
-      end
-
       def apply_default_config(config)
         HashUtil.deep_merge(Config.default_config, config)
       end

data/lib/html2rss/{configuration.rb → defaults.rb}

@@ -2,8 +2,8 @@
 
 module Html2rss
   ##
-  # Global configuration defaults for the Html2rss gem.
-  class Configuration
+  # Global defaults for the Html2rss gem.
+  class Defaults
     # The valid symbol log levels.
     VALID_LOG_LEVELS = %i[debug info warn error fatal unknown].freeze
 
@@ -29,7 +29,7 @@ module Html2rss
     attr_reader :stylesheets
 
     ##
-    # Initializes a new Configuration instance with defaults.
+    # Initializes a new Defaults instance.
     def initialize
       @logger_formatter = proc do |severity, datetime, _progname, msg|
         "#{datetime} [#{severity}] #{msg}\n"
@@ -93,11 +93,13 @@ module Html2rss
     end
 
     ##
-    # Sets the default strategy.
+    # Sets the default feed-level strategy plan (+:auto+ or a concrete transport strategy).
     #
-    # @param strategy [Symbol, String, nil] the strategy name
-    # @return [Symbol, nil] the normalized strategy name
-    # @raise [ArgumentError] if the strategy is not registered
+    # +:auto+ is not a {RequestService} adapter — it is resolved by {FeedPipeline::StrategyPlan}.
+    #
+    # @param strategy [Symbol, String, nil] the strategy plan name
+    # @return [Symbol, nil] the normalized strategy plan name
+    # @raise [ArgumentError] if the strategy plan is unknown
     def default_strategy=(strategy)
       if strategy.nil?
         @default_strategy = nil
@@ -107,7 +109,7 @@ module Html2rss
         end
 
         normalized = strategy.to_sym
-        raise ArgumentError, "unknown strategy: #{strategy}" unless RequestService.strategy_registered?(normalized)
+        raise ArgumentError, "unknown strategy: #{strategy}" unless FeedPipeline::StrategyPlan.valid?(normalized)
 
         @default_strategy = normalized
       end
@@ -148,9 +150,9 @@ module Html2rss
     protected
 
     ##
-    # Copy constructor for duplicating configuration.
+    # Copy constructor for duplicating defaults.
     #
-    # @param other [Html2rss::Configuration] the original configuration
+    # @param other [Html2rss::Defaults] the original defaults
     # @return [void]
     def initialize_copy(other)
       super

data/lib/html2rss/feed_builder/item_presentation.rb

@@ -0,0 +1,42 @@
+# frozen_string_literal: true
+
+module Html2rss
+  module FeedBuilder
+    ##
+    # Presentation rules for rendering an {Html2rss::Article} into feed wire formats.
+    #
+    # Owns description enrichment ({Html::Rendering::DescriptionBuilder}) and RSS
+    # non-image enclosure selection. {Article} keeps raw extracted fields only.
+    module ItemPresentation
+      class << self
+        ##
+        # @param article [Html2rss::Article]
+        # @return [String, nil] sanitized description HTML/text for feed item bodies
+        def description_for(article)
+          Html::Rendering::DescriptionBuilder.new(
+            base: article.description,
+            title: article.title,
+            url: article.url,
+            enclosures: article.enclosures,
+            image: article.image
+          ).call
+        end
+
+        ##
+        # First non-image enclosure for RSS +enclosure+ (images stay on description / JSON Feed).
+        #
+        # @param article [Html2rss::Article]
+        # @return [Html2rss::Article::Enclosure, nil]
+        def rss_enclosure_for(article)
+          article.enclosures.find { |enc| !image_mime_type?(enc.type) }
+        end
+
+        private
+
+        def image_mime_type?(type)
+          type.to_s.downcase.start_with?('image/')
+        end
+      end
+    end
+  end
+end