html2rss 0.18.0 → 0.19.0

data/lib/html2rss/rss_builder/enclosure.rb

@@ -22,6 +22,9 @@ module Html2rss
         content_type.first&.to_s || 'application/octet-stream'
       end
 
+      # @param enclosure [Html2rss::RssBuilder::Enclosure, nil] built enclosure object for the current RSS item
+      # @param maker [RSS::Maker::RSS20::ItemsBase::ItemBase] RSS item builder
+      # @return [void]
       def self.add(enclosure, maker)
         return unless enclosure
 
@@ -32,6 +35,9 @@ module Html2rss
         end
       end
 
+      # @param url [Html2rss::Url] absolute enclosure URL
+      # @param type [String, nil] optional enclosure MIME type
+      # @param bits_length [Integer] enclosure byte length (historical name)
       def initialize(url:, type: nil, bits_length: 0)
         raise ArgumentError, 'An Enclosure requires an absolute URL' if !url || !url.absolute?
 
@@ -40,9 +46,17 @@ module Html2rss
         @bits_length = bits_length
       end
 
+      # @return [String] explicit MIME type or one inferred from URL extension
       def type = @type || self.class.guess_content_type_from_url(url)
 
-      attr_reader :bits_length, :url
+      # @return [Integer] enclosure length in bytes
+      def bytes_length = @bits_length
+
+      # @return [Integer] enclosure length in bytes (legacy reader name)
+      def bits_length = bytes_length
+
+      # @return [Html2rss::Url] absolute enclosure URL
+      attr_reader :url
     end
   end
 end

data/lib/html2rss/rss_builder/stylesheet.rb

@@ -35,8 +35,12 @@ module Html2rss
         end
       end
 
+      # Allowed stylesheet MIME types for RSS processing instructions.
       TYPES = ['text/css', 'text/xsl'].to_set.freeze
 
+      # @param href [String] stylesheet URL
+      # @param type [String] MIME type (`text/css` or `text/xsl`)
+      # @param media [String] media query hint for the stylesheet
       def initialize(href:, type:, media: 'all')
         raise ArgumentError, 'stylesheet.href must be a String' unless href.is_a?(String)
         raise ArgumentError, 'stylesheet.type invalid' unless TYPES.include?(type)

data/lib/html2rss/rss_builder.rb

@@ -7,6 +7,9 @@ module Html2rss
   # Builds an RSS Feed by providing channel, articles and stylesheets.
   class RssBuilder
     class << self
+      # @param article [Html2rss::RssBuilder::Article] source article
+      # @param item_maker [RSS::Maker::RSS20::ItemsBase::ItemBase] RSS item builder
+      # @return [void]
       def add_item(article, item_maker)
         add_item_string_values(article, item_maker)
         add_item_categories(article, item_maker)
@@ -50,6 +53,7 @@ module Html2rss
       @stylesheets = stylesheets
     end
 
+    # @return [RSS::Rss] RSS 2.0 document instance
     def call
       RSS::Maker.make('2.0') do |maker|
         Stylesheet.add(maker, stylesheets)

data/lib/html2rss/selectors/config.rb

@@ -7,6 +7,7 @@ module Html2rss
     ##
     # Validates the configuration hash for :selectors.
     class Config < Dry::Validation::Contract
+      # Required wrapper key used to validate dynamic selector names.
       NESTING_KEY = :dynamic_keys_workaround
 
       ##

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

@@ -32,6 +32,8 @@ module Html2rss
         #
         # @param xml [Nokogiri::XML::Element]
         # @param options [Options]
+        # @option options [String] :selector CSS selector used to find the element
+        # @option options [String] :attribute attribute name to extract from the selected element
         def initialize(xml, options)
           @options = options
           @element = Extractors.element(xml, options.selector)

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

@@ -32,6 +32,8 @@ module Html2rss
         #
         # @param xml [Nokogiri::XML::Element]
         # @param options [Options]
+        # @option options [String] :selector CSS selector used to find the link element
+        # @option options [Hash{Symbol => Object}] :channel channel configuration, including :url
         def initialize(xml, options)
           @options = options
           @element = Extractors.element(xml, options.selector)

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

@@ -31,6 +31,7 @@ module Html2rss
         #
         # @param xml [Nokogiri::XML::Element]
         # @param options [Options]
+        # @option options [String] :selector CSS selector used to find the element
         def initialize(xml, options)
           @element = Extractors.element(xml, options.selector)
         end

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

@@ -9,7 +9,7 @@ module Html2rss
       # Example usage in YAML:
       #
       #    selectors:
-      #      author:
+      #      byline:
       #        extractor: static
       #        static: Foobar
       #
@@ -24,6 +24,7 @@ module Html2rss
         #
         # @param _xml [nil, Nokogiri::XML::Element] Unused parameter for compatibility with other extractors.
         # @param options [Options] Options containing the static value.
+        # @option options [String, Symbol] :static static value returned by this extractor
         def initialize(_xml, options)
           @options = options
         end

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

@@ -29,6 +29,7 @@ module Html2rss
         #
         # @param xml [Nokogiri::XML::Element]
         # @param options [Options]
+        # @option options [String] :selector CSS selector used to find the element
         def initialize(xml, options)
           @element = Extractors.element(xml, options.selector)
         end

data/lib/html2rss/selectors/extractors.rb

@@ -23,6 +23,7 @@ module Html2rss
         hash[klass] = klass.const_get(:Options)
       end
 
+      # Extractor used when none is explicitly configured.
       DEFAULT_EXTRACTOR = :text
 
       class << self
@@ -36,7 +37,7 @@ module Html2rss
           selector ? xml.css(selector) : xml
         end
 
-        # @param attribute_options [Hash<Symbol, Object>]
+        # @param attribute_options [Hash{Symbol => Object}]
         #   Should contain at least `:extractor` (the name) and required options for that extractor.
         # @param xml [Nokogiri::XML::Document]
         # @return [Object] instance of the specified item extractor class

data/lib/html2rss/selectors/object_to_xml_converter.rb

@@ -7,6 +7,7 @@ module Html2rss
     ##
     # A naive implementation of "Object to XML": converts a Ruby object to XML format.
     class ObjectToXmlConverter
+      # Wrapper tags used for top-level collection conversion.
       OBJECT_TO_XML_TAGS = {
         hash: ['<object>', '</object>'],
         array: ['<array>', '</array>']

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

@@ -9,7 +9,8 @@ module Html2rss
         # Validates the presence of required options in the context
         #
         # @param keys [Array<Symbol>] the keys to check for presence
-        # @param context [Hash] the context containing options
+        # @param context [Selectors::Context] the context containing options
+        # @return [void]
         # @raise [MissingOption] if any key is missing
         def self.expect_options(keys, context)
           keys.each do |key|
@@ -25,13 +26,14 @@ module Html2rss
         # @param value [Object] the value to check
         # @param types [Array<Class>, Class] the expected type(s)
         # @param name [String] the name of the option being checked
-        # @param context [Selectors::Context] the context
+        # @param context [Selectors::Context] call-site context used for richer validation errors
+        # @return [void]
         # @raise [InvalidType] if the value is not of the expected type(s)
         def self.assert_type(value, types = [], name, context:)
           return if Array(types).any? { |type| value.is_a?(type) }
 
-          options = if context.is_a?(Hash)
-                      context[:options]
+          options = if context.respond_to?(:options)
+                      context.options
                     else
                       { file: File.basename(caller(1, 1).first.split(':').first) }
                     end
@@ -42,6 +44,10 @@ module Html2rss
 
         ##
         # This method validates the arguments passed to the post processor. Must be implemented by subclasses.
+        #
+        # @param _value [Object] extracted selector value
+        # @param _context [Selectors::Context] post-processor execution context
+        # @return [void]
         def self.validate_args!(_value, _context)
           raise NotImplementedError, 'You must implement the `validate_args!` method in the post processor'
         end
@@ -49,11 +55,10 @@ module Html2rss
         # Initializes the post processor
         #
         # @param value [Object] the value to be processed
-        # @param context [Selectors::Context] the context
+        # @param context [Selectors::Context] runtime selector context and options
         def initialize(value, context)
           klass = self.class
-          # TODO: get rid of Hash
-          klass.assert_type(context, [Selectors::Context, Hash], 'context', context:)
+          klass.assert_type(context, Selectors::Context, 'context', context:)
           klass.validate_args!(value, context)
 
           @value = value
@@ -64,6 +69,7 @@ module Html2rss
 
         # Abstract method to be implemented by subclasses
         #
+        # @return [Object] transformed value
         # @raise [NotImplementedError] if not implemented in subclass
         def get
           raise NotImplementedError, 'You must implement the `get` method in the post processor'

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

@@ -29,6 +29,9 @@ module Html2rss
       #
       # See the doc on [String#gsub](https://ruby-doc.org/core/String.html#method-i-gsub) for more info.
       class Gsub < Base
+        # @param value [String] extracted selector value
+        # @param context [Selectors::Context] post-processor context
+        # @return [void]
         def self.validate_args!(value, context)
           assert_type value, String, :value, context:
           expect_options(%i[replacement pattern], context)

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

@@ -28,6 +28,9 @@ module Html2rss
       # Would return:
       #    'Lorem **ipsum** dolor'
       class HtmlToMarkdown < Base
+        # @param value [String] extracted selector value
+        # @param context [Selectors::Context] post-processor context
+        # @return [void]
         def self.validate_args!(value, context)
           assert_type value, String, :value, context:
         end

data/lib/html2rss/selectors/post_processors/html_transformers/transform_urls_to_absolute_ones.rb

@@ -3,10 +3,12 @@
 module Html2rss
   class Selectors
     module PostProcessors
+      # HTML tree transformers used by selectors post-processing.
       module HtmlTransformers
         ##
         # Transformer that converts relative URLs to absolute URLs within specified HTML elements.
         class TransformUrlsToAbsoluteOnes
+          # HTML tags and the URL-bearing attribute that should be normalized.
           URL_ELEMENTS_WITH_URL_ATTRIBUTE = {
             'a' => :href, # Visible link
             'img' => :src, # Visible image
@@ -15,12 +17,19 @@ module Html2rss
             'video' => :src # Video player is visible
           }.freeze
 
+          # @param channel_url [String, Html2rss::Url] base URL used to resolve relative links
           def initialize(channel_url)
             @channel_url = channel_url
           end
 
           ##
           # Transforms URLs to absolute ones.
+          #
+          # @param node_name [String] node name currently being transformed
+          # @param node [Nokogiri::XML::Node] node currently being transformed
+          # @param _env [Hash] transformer context
+          # @option _env [Object] :_reserved reserved for transformer pipeline context
+          # @return [void]
           def call(node_name:, node:, **_env)
             return unless URL_ELEMENTS_WITH_URL_ATTRIBUTE.key?(node_name)
 

data/lib/html2rss/selectors/post_processors/html_transformers/wrap_img_in_a.rb

@@ -12,6 +12,8 @@ module Html2rss
           #
           # @param node_name [String]
           # @param node [Nokogiri::XML::Node]
+          # @param _env [Hash] transformer context
+          # @option _env [Object] :_reserved reserved for transformer pipeline context
           # @return [nil]
           def call(node_name:, node:, **_env)
             return unless should_process?(node_name)
@@ -19,10 +21,14 @@ module Html2rss
             wrap_image_in_anchor(node) unless already_wrapped?(node)
           end
 
+          # @param node_name [String] node name currently being transformed
+          # @return [Boolean] whether this transformer should run for the node
           def should_process?(node_name)
             node_name == 'img'
           end
 
+          # @param node [Nokogiri::XML::Node] node currently being transformed
+          # @return [Boolean] whether the image is already wrapped in a link
           def already_wrapped?(node)
             node.parent.name == 'a'
           end

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

@@ -34,6 +34,9 @@ module Html2rss
       #
       #    <p>Price: 12.34</p>
       class MarkdownToHtml < Base
+        # @param value [String] extracted selector value
+        # @param context [Selectors::Context] post-processor context
+        # @return [void]
         def self.validate_args!(value, context)
           assert_type value, String, :value, context:
         end

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

@@ -27,6 +27,9 @@ module Html2rss
       #
       # It uses `Time.parse`.
       class ParseTime < Base
+        # @param value [String] extracted selector value
+        # @param context [Selectors::Context] post-processor context
+        # @return [void]
         def self.validate_args!(value, context)
           assert_type(value, String, :value, context:)
           time_zone_value = time_zone(context)
@@ -38,6 +41,8 @@ module Html2rss
           assert_type(time_zone_value, String, :time_zone, context:)
         end
 
+        # @param context [Selectors::Context] post-processor context
+        # @return [String, nil] configured channel time zone
         def self.time_zone(context) = context.dig(:config, :channel, :time_zone)
 
         ##

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

@@ -23,6 +23,9 @@ module Html2rss
       # Would return:
       #    'http://why-not-use-a-link.uh'
       class ParseUri < Base
+        # @param value [String] extracted selector value
+        # @param _context [Selectors::Context] post-processor context
+        # @return [void]
         def self.validate_args!(value, _context)
           raise ArgumentError, 'The `value` option is missing or empty.' if value.to_s.empty?
         end

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

@@ -83,6 +83,9 @@ module Html2rss
             'preload' => 'none'
           }
         }.freeze
+        # @param value [String] extracted selector value
+        # @param context [Selectors::Context] post-processor context
+        # @return [void]
         def self.validate_args!(value, context)
           assert_type value, String, :value, context:
         end
@@ -95,7 +98,8 @@ module Html2rss
         def self.get(html, url)
           return nil if String(html).empty?
 
-          new(html, config: { channel: { url: } }).get
+          context = Selectors::Context.new(config: { channel: { url: } }, options: {})
+          new(html, context).get
         end
 
         ##

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

@@ -30,6 +30,9 @@ module Html2rss
       # Would return:
       #    'bar'
       class Substring < Base
+        # @param value [String] extracted selector value
+        # @param context [Selectors::Context] post-processor context
+        # @return [void]
         def self.validate_args!(value, context)
           assert_type value, String, :value, context:
 

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

@@ -34,6 +34,9 @@ module Html2rss
       # Would return:
       #    'Product (23,42€)'
       class Template < Base
+        # @param value [String] extracted selector value
+        # @param context [Selectors::Context] post-processor context
+        # @return [void]
         def self.validate_args!(value, context)
           assert_type value, String, :value, context:
 

data/lib/html2rss/selectors/post_processors.rb

@@ -34,6 +34,11 @@ module Html2rss
 
       ##
       # Shorthand method to instantiate the post processor and call `#get` on it
+      #
+      # @param name [String, Symbol] post-processor name from selector config
+      # @param value [Object] extracted selector value
+      # @param context [Selectors::Context] post-processor context
+      # @return [Object] transformed selector value
       def self.get(name, value, context)
         klass = NAME_TO_CLASS[name.to_sym] || raise(UnknownPostProcessorName, "Unknown name '#{name}'")
         klass.new(value, context).get

data/lib/html2rss/selectors.rb

@@ -20,10 +20,14 @@ module Html2rss
     # A context instance passed to item extractors and post-processors.
     Context = Struct.new('Context', :options, :item, :config, :scraper, keyword_init: true) # rubocop:disable Style/RedundantStructKeywordInit
 
+    # Default selectors options merged into user configuration.
     DEFAULT_CONFIG = { items: { enhance: true } }.freeze
 
+    # Selector key that points to the root list of article nodes.
     ITEMS_SELECTOR_KEY = :items
+    # Supported RSS item attributes extractable through selectors.
     ITEM_TAGS = %i[title url description author comments published_at guid enclosure categories].freeze
+    # Item attributes that require dedicated extraction logic.
     SPECIAL_ATTRIBUTES = Set[:guid, :enclosure, :categories].freeze
 
     # Mapping of new attribute names to their legacy names for backward compatibility.
@@ -85,6 +89,7 @@ module Html2rss
     # Extracts an article hash for a given item element.
     #
     # @param item [Nokogiri::XML::Element] The element to extract from.
+    # @param page_response [RequestService::Response] response used for selector extraction context
     # @return [Hash] Hash of attributes for the article.
     def extract_article(item, page_response = response)
       @rss_item_attributes.to_h { |key| [key, select(key, item, base_url: page_response.url)] }.compact
@@ -96,6 +101,7 @@ module Html2rss
     #
     # @param article_hash [Hash] The original article hash.
     # @param article_tag [Nokogiri::XML::Element] HTML element to extract additional info from.
+    # @param base_url [String, Html2rss::Url] base URL for normalization during enhancement
     # @return [Hash] The enhanced article hash.
     def enhance_article_hash(article_hash, article_tag, base_url = @url)
       selected_anchor = HtmlExtractor.main_anchor_for(article_tag)
@@ -116,6 +122,7 @@ module Html2rss
     #
     # @param name [Symbol, String] Name of the attribute.
     # @param item [Nokogiri::XML::Element] The HTML element to process.
+    # @param base_url [String, Html2rss::Url] base URL for relative extraction values
     # @return [Object, Array<Object>] The selected value(s).
     # @raise [InvalidSelectorName] If the attribute name is invalid or not defined.
     def select(name, item, base_url: @url)

data/lib/html2rss/url.rb

@@ -25,6 +25,7 @@ module Html2rss
 
     # Regular expression for basic URI format validation
     URI_REGEXP = Addressable::URI::URIREGEX
+    # Schemes accepted by channel URL validation.
     SUPPORTED_SCHEMES = %w[http https].to_set.freeze
 
     ##
@@ -107,7 +108,10 @@ module Html2rss
     def self.validate_channel_url(url)
       raise ArgumentError, 'URL must be absolute' unless url.absolute?
 
-      raise ArgumentError, 'URL must not contain an @ character' if url.to_s.include?('@')
+      uri = Addressable::URI.parse(url.to_s)
+      has_forbidden_at = uri.user || uri.password
+      has_forbidden_at ||= [uri.query, uri.fragment].compact.any? { |value| value.include?('@') }
+      raise ArgumentError, 'URL must not contain an @ character' if has_forbidden_at
 
       scheme = url.scheme
       raise ArgumentError, "URL scheme '#{scheme}' is not supported" unless SUPPORTED_SCHEMES.include?(scheme)
@@ -122,31 +126,41 @@ module Html2rss
       freeze
     end
 
-    # Delegate common URI operations to the underlying URI
+    # @return [String] normalized URL string
     def to_s = @uri.to_s
+
+    # @return [String, nil] URI scheme, for example `http` or `https`
     def scheme = @uri.scheme
+
+    # @return [String, nil] URI host component
     def host = @uri.host
+
+    # @return [Integer, nil] URI port component
     def port = @uri.port
+
+    # @return [String, nil] URI path component
     def path = @uri.path
+
+    # @return [String, nil] URI query string without leading `?`
     def query = @uri.query
+
+    # @return [String, nil] URI fragment without leading `#`
     def fragment = @uri.fragment
+
+    # @return [Boolean] whether the URL includes scheme and host
     def absolute? = @uri.absolute?
 
     ##
     # Returns the URL query string as a hash of string keys and values.
     #
     # @return [Hash{String => String}] normalized query parameters
-    def query_values
-      @uri.query_values(Hash) || {}
-    end
+    def query_values = @uri.query_values(Hash) || {}
 
     ##
     # Returns the URL path split into non-empty segments.
     #
     # @return [Array<String>] normalized path segments
-    def path_segments
-      @uri.path.to_s.split('/').reject(&:empty?)
-    end
+    def path_segments = @uri.path.to_s.split('/').reject(&:empty?)
 
     ##
     # Returns a copy of the URL with the provided path.
@@ -221,42 +235,32 @@ module Html2rss
     #
     # @param other [Url] the other URL to compare with
     # @return [Integer] -1, 0, or 1 for less than, equal, or greater than
-    def <=>(other)
-      to_s <=> other.to_s
-    end
+    def <=>(other) = to_s <=> other.to_s
 
     ##
     # Returns true if this URL is equal to another URL.
     #
     # @param other [Object] the other object to compare with
     # @return [Boolean] true if the URLs are equal
-    def ==(other)
-      other.is_a?(Url) && to_s == other.to_s
-    end
+    def ==(other) = other.is_a?(Url) && to_s == other.to_s
 
     ##
     # Supports hash-based comparisons by ensuring equality semantics match `hash`.
     #
     # @param other [Object] the other object to compare with
     # @return [Boolean] true if the URLs are considered equal
-    def eql?(other)
-      other.is_a?(Url) && to_s == other.to_s
-    end
+    def eql?(other) = other.is_a?(Url) && to_s == other.to_s
 
     ##
     # Returns the hash code for this URL.
     #
     # @return [Integer] the hash code
-    def hash
-      to_s.hash
-    end
+    def hash = to_s.hash
 
     ##
     # Returns a string representation of the URL for debugging.
     #
     # @return [String] the debug representation
-    def inspect
-      "#<#{self.class}:#{object_id} @uri=#{@uri.inspect}>"
-    end
+    def inspect = "#<#{self.class}:#{object_id} @uri=#{@uri.inspect}>"
   end
 end

data/lib/html2rss/version.rb

@@ -3,6 +3,7 @@
 ##
 # The Html2rss namespace.
 module Html2rss
-  VERSION = '0.18.0'
+  # Current application version.
+  VERSION = '0.19.0'
   public_constant :VERSION
 end