html2rss 0.30.0 → 0.31.0

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

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
 
+require 'date'
 require 'time'
 require 'tzinfo'
 
@@ -27,7 +28,13 @@ module Html2rss
       #
       # It uses `Time.parse`.
       class ParseTime < Base
-        # JSON Schema description exported via +schema_doc+.
+        # Expected Ruby class for the extracted value before this post-processor runs.
+        VALUE_TYPE = String
+
+        # Config-facing options contract (none).
+        OPTIONS = [].freeze
+
+        # JSON Schema description exported via +schema_export+.
         DESCRIPTION = 'Parse a time string with Time.parse and return RFC822, using the channel `time_zone`.'
 
         # Example post-process objects for JSON Schema +examples+.
@@ -36,14 +43,29 @@ module Html2rss
         ].freeze
 
         # @return [Hash{Symbol => Object}] JSON Schema fragment for this post-processor
-        def self.schema_doc = SchemaDoc.for_post_processor(name: :parse_time, klass: self)
+        def self.schema_export = SchemaExport.for_post_processor(name: :parse_time, klass: self)
+
+        # @param identifier [String] IANA time zone name
+        # @return [TZInfo::Timezone]
+        def self.timezone(identifier)
+          timezones[identifier] ||= TZInfo::Timezone.get(identifier)
+        end
 
-        # @param value [String] extracted selector value
-        # @param context [Selectors::Context] post-processor context
+        # rubocop:disable-next ThreadSafety/ClassInstanceVariable
+        def self.timezones
+          @timezones ||= {}
+        end
+        private_class_method :timezones
+
+        ##
+        # Ensures +context.time_zone+ is a non-empty String before parsing.
+        #
+        # @param _value [String] extracted time string (unused; type-checked via VALUE_TYPE)
+        # @param context [Selectors::StepEnv] must carry a usable +time_zone+
         # @return [void]
-        def self.validate_args!(value, context)
-          assert_type(value, String, :value, context:)
-          time_zone_value = time_zone(context)
+        # @raise [ArgumentError] when time_zone is nil or empty
+        def self.validate_args!(_value, context)
+          time_zone_value = context.time_zone
 
           if time_zone_value.nil? || time_zone_value.empty?
             raise ArgumentError, 'time_zone cannot be nil or empty', [], cause: nil
@@ -52,36 +74,38 @@ 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)
-
         ##
         # Converts the provided time string to RFC822 format, taking into account the time_zone.
         #
+        # Uses in-memory {TZInfo::Timezone} conversion so parsing never mutates +ENV['TZ']+
+        # (which would invalidate libc +tzset+ and re-read zoneinfo from disk).
+        #
         # @return [String] RFC822 formatted time
         # @raise [TZInfo::InvalidTimezoneIdentifier] if the configured time zone is invalid
-        def get
-          with_timezone(time_zone) { Time.parse(value).rfc822 }
+        def call
+          parse_time(value, context.time_zone).rfc822
         end
 
         private
 
-        def time_zone
-          self.class.time_zone(context)
+        def parse_time(string, time_zone)
+          components = Date._parse(string, false)
+          if components[:zone] || components.key?(:offset)
+            Time.parse(string)
+          else
+            local_time_in_zone(components, time_zone)
+          end
         end
 
-        def with_timezone(time_zone)
-          return yield if time_zone.nil? || time_zone.empty?
-
-          # Validate timezone using TZInfo
-          TZInfo::Timezone.get(time_zone)
-
-          prev_tz = ENV.fetch('TZ', Time.now.getlocal.zone)
-          ENV['TZ'] = time_zone
-          yield
-        ensure
-          ENV['TZ'] = prev_tz if prev_tz
+        def local_time_in_zone(components, time_zone)
+          self.class.timezone(time_zone).local_time(
+            components[:year],
+            components[:mon],
+            components[:mday],
+            components[:hour] || 0,
+            components[:min] || 0,
+            (components[:sec] || 0) + (components[:sec_fraction] || 0)
+          )
         end
       end
     end

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

@@ -23,7 +23,13 @@ module Html2rss
       # Would return:
       #    'http://why-not-use-a-link.uh'
       class ParseUri < Base
-        # JSON Schema description exported via +schema_doc+.
+        # Expected Ruby class for the extracted value; any type is accepted.
+        VALUE_TYPE = nil
+
+        # Config-facing options contract (none).
+        OPTIONS = [].freeze
+
+        # JSON Schema description exported via +schema_export+.
         DESCRIPTION = 'Normalize a URL string; resolve relative URLs against the channel URL.'
 
         # Example post-process objects for JSON Schema +examples+.
@@ -32,10 +38,10 @@ module Html2rss
         ].freeze
 
         # @return [Hash{Symbol => Object}] JSON Schema fragment for this post-processor
-        def self.schema_doc = SchemaDoc.for_post_processor(name: :parse_uri, klass: self)
+        def self.schema_export = SchemaExport.for_post_processor(name: :parse_uri, klass: self)
 
         # @param value [String] extracted selector value
-        # @param _context [Selectors::Context] post-processor context
+        # @param _context [Selectors::StepEnv] 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?
@@ -43,10 +49,8 @@ module Html2rss
 
         ##
         # @return [String]
-        def get
-          config_url = context.dig(:config, :channel, :url)
-
-          Url.from_relative(value, config_url).to_s
+        def call
+          Url.from_relative(value, context.base_url).to_s
         end
       end
     end

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

@@ -38,7 +38,13 @@ module Html2rss
       # Would return:
       #    '<p>Lorem <b>ipsum</b> dolor ...</p>'
       class SanitizeHtml < Base
-        # JSON Schema description exported via +schema_doc+.
+        # Expected Ruby class for the extracted value before this post-processor runs.
+        VALUE_TYPE = String
+
+        # Config-facing options contract (none).
+        OPTIONS = [].freeze
+
+        # JSON Schema description exported via +schema_export+.
         DESCRIPTION = 'Sanitize HTML (sanitize gem RELAXED plus html2rss defaults: absolute URLs, ' \
                       'safe link/img attributes, wrap lone images in anchors).'
 
@@ -92,21 +98,18 @@ module Html2rss
         }.freeze
 
         # @return [Hash{Symbol => Object}] JSON Schema fragment for this post-processor
-        def self.schema_doc = SchemaDoc.for_post_processor(name: :sanitize_html, klass: self)
-
-        # @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
+        def self.schema_export = SchemaExport.for_post_processor(name: :sanitize_html, klass: self)
 
         ##
-        # @param html [String]
-        # @param url [String, Html2rss::Url]
-        # @return [String, nil]
+        # Cached standalone helper: sanitizes an HTML string with a memoized fragment cache.
+        # Used outside the selector pipeline (e.g. by DescriptionBuilder).
+        # Distinct from {#call}, which executes as a post-processor strategy instance.
+        #
+        # @param html [String] raw HTML text to sanitize
+        # @param url [String, Html2rss::Url] base URL for relative link/image resolution
+        # @return [String, nil] sanitized HTML string or nil if empty
         # rubocop:disable-next ThreadSafety/ClassInstanceVariable
-        def self.get(html, url)
+        def self.call(html, url)
           return nil if String(html).empty?
 
           @fragment_cache ||= {}
@@ -114,24 +117,45 @@ module Html2rss
           return @fragment_cache[key] if @fragment_cache.key?(key)
 
           @fragment_cache.clear if @fragment_cache.size > 256
-          context = Selectors::Context.new(config: { channel: { url: } }, options: {})
-          @fragment_cache[key] = new(html, context).get
+          @fragment_cache[key] = sanitize(html, url)
         end
 
         ##
-        # @param channel_url [String, Html2rss::Url]
+        # Pure HTML sanitization with preserved newlines and absolute URL resolution.
+        #
+        # @param html [String]
+        # @param base_url [String, Html2rss::Url]
+        # @return [String, nil]
+        def self.sanitize(html, base_url)
+          return nil if String(html).empty?
+
+          # Temporarily replace newlines with a placeholder to preserve them during space collapsing
+          temp_value = html.to_s.gsub("\n", ' __NEWLINE_PLACEHOLDER__ ')
+          sanitized_html = Sanitize.fragment(temp_value, sanitize_config(base_url)).to_s
+          sanitized_html.gsub!(/\s+/, ' ')
+
+          # Restore newlines and clean up surrounding whitespace
+          sanitized_html.gsub!(/[ \t\r]*__NEWLINE_PLACEHOLDER__[ \t\r]*/, "\n")
+          sanitized_html.gsub!(/\n{3,}/, "\n\n")
+
+          sanitized_html.strip!
+          sanitized_html.empty? ? nil : sanitized_html
+        end
+
+        ##
+        # @param base_url [String, Html2rss::Url]
         # @return [Hash] the memoized sanitize configuration
         # rubocop:disable-next Metrics/MethodLength, ThreadSafety/ClassInstanceVariable
-        def self.sanitize_config(channel_url)
+        def self.sanitize_config(base_url)
           @sanitize_configs ||= {}
-          @sanitize_configs[channel_url] ||= begin
+          @sanitize_configs[base_url] ||= begin
             config = Sanitize::Config.merge(
               Sanitize::Config::RELAXED,
               attributes: { all: %w[dir lang alt title translate] },
               add_attributes: TAG_ATTRIBUTES,
               transformers: [
                 lambda { |env|
-                  HtmlTransformers::TransformUrlsToAbsoluteOnes.new(channel_url).call(**env)
+                  HtmlTransformers::TransformUrlsToAbsoluteOnes.new(base_url).call(**env)
                 },
                 ->(env) { HtmlTransformers::WrapImgInA.new.call(**env) }
               ]
@@ -145,23 +169,13 @@ module Html2rss
 
         ##
         # @return [String, nil]
-        def get
-          # Temporarily replace newlines with a placeholder to preserve them during space collapsing
-          temp_value = value.to_s.gsub("\n", ' __NEWLINE_PLACEHOLDER__ ')
-          sanitized_html = Sanitize.fragment(temp_value, self.class.sanitize_config(channel_url)).to_s
-          sanitized_html.gsub!(/\s+/, ' ')
-
-          # Restore newlines and clean up surrounding whitespace
-          sanitized_html.gsub!(/[ \t\r]*__NEWLINE_PLACEHOLDER__[ \t\r]*/, "\n")
-          sanitized_html.gsub!(/\n{3,}/, "\n\n")
-
-          sanitized_html.strip!
-          sanitized_html.empty? ? nil : sanitized_html
+        def call
+          self.class.sanitize(value, base_url)
         end
 
         private
 
-        def channel_url = context.dig(:config, :channel, :url)
+        def base_url = context.base_url
       end
     end
   end

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

@@ -30,16 +30,16 @@ module Html2rss
       # Would return:
       #    'bar'
       class Substring < Base
-        # Required config field types (validator introspection via +Options+).
-        OPTION_TYPES = { start: Integer }.freeze
+        # Expected Ruby class for the extracted value before this post-processor runs.
+        VALUE_TYPE = String
 
-        # Optional config field types (validated when the key is present and non-nil).
-        OPTIONAL_OPTION_TYPES = { end: Integer }.freeze
-
-        # Config fields required by this post-processor (validator / schema introspection).
-        Options = Struct.new(*OPTION_TYPES.keys, keyword_init: true)
+        # Config-facing options contract (validator / SchemaExport / Base.validate_options!).
+        OPTIONS = [
+          OptionSpec.new(name: :start, type: Integer),
+          OptionSpec.new(name: :end, type: Integer, required: false)
+        ].freeze
 
-        # JSON Schema description exported via +schema_doc+.
+        # JSON Schema description exported via +schema_export+.
         DESCRIPTION = 'Return a slice of the extracted string using Integer `start` and optional `end` ' \
                       '(Ruby String#[] range semantics; end may be omitted).'
 
@@ -49,24 +49,13 @@ module Html2rss
         ].freeze
 
         # @return [Hash{Symbol => Object}] JSON Schema fragment for this post-processor
-        def self.schema_doc = SchemaDoc.for_post_processor(name: :substring, klass: self)
-
-        # @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:)
-
-          options = context[:options]
-          assert_type(options[:start], Integer, :start, context:)
-          assert_type(options[:end], Integer, :end, context:) if options.key?(:end)
-        end
+        def self.schema_export = SchemaExport.for_post_processor(name: :substring, klass: self)
 
         ##
         # Extracts the substring from the original string based on the provided start and end indices.
         #
         # @return [String, nil] The extracted substring.
-        def get
+        def call
           value[range]
         end
 
@@ -75,12 +64,12 @@ module Html2rss
         #
         # @return [Range] The range object representing the start and end/Infinity (integers).
         def range
-          options = context[:options]
-          start = options[:start]
+          step_config = context.step_config
+          start = step_config[:start]
 
-          return (start..) unless options.key?(:end)
+          return (start..) unless step_config.key?(:end)
 
-          finish = options[:end]
+          finish = step_config[:end]
           raise ArgumentError, 'The `start` value must be unequal to the `end` value.' if start == finish
 
           (start..finish)

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

@@ -34,13 +34,15 @@ module Html2rss
       # Would return:
       #    'Product (23,42€)'
       class Template < Base
-        # Required config field types (validator introspection via +Options+).
-        OPTION_TYPES = { string: String }.freeze
+        # Expected Ruby class for the extracted value before this post-processor runs.
+        VALUE_TYPE = String
 
-        # Config fields required by this post-processor (validator / schema introspection).
-        Options = Struct.new(*OPTION_TYPES.keys, keyword_init: true)
+        # Config-facing options contract (validator / SchemaExport / Base.validate_options!).
+        OPTIONS = [
+          OptionSpec.new(name: :string, type: String)
+        ].freeze
 
-        # JSON Schema description exported via +schema_doc+.
+        # JSON Schema description exported via +schema_export+.
         # rubocop:disable Style/FormatStringToken -- documents Kernel#format `%{key}` placeholders
         DESCRIPTION = 'Format a string with Kernel#format-style placeholders (`%{key}` / `%<key>s`). ' \
                       '`%{self}` is the current selector value; other keys resolve sibling selectors.'
@@ -52,36 +54,38 @@ module Html2rss
         # rubocop:enable Style/FormatStringToken
 
         # @return [Hash{Symbol => Object}] JSON Schema fragment for this post-processor
-        def self.schema_doc = SchemaDoc.for_post_processor(name: :template, klass: self)
+        def self.schema_export = SchemaExport.for_post_processor(name: :template, klass: self)
 
-        # @param value [String] extracted selector value
-        # @param context [Selectors::Context] post-processor context
+        ##
+        # Ensures a non-empty template +string+ option and an +item_env+ for sibling lookup.
+        #
+        # @param _value [String] current selector value (unused here)
+        # @param context [Selectors::StepEnv] must include step_config[:string] and item_env
         # @return [void]
-        def self.validate_args!(value, context)
-          assert_type value, String, :value, context:
-
-          string = context[:options]&.dig(:string).to_s
+        # @raise [InvalidType] when the template string is blank
+        # @raise [MissingOption] when item_env is missing
+        def self.validate_args!(_value, context)
+          string = context.step_config[:string].to_s
           raise InvalidType, 'The `string` template is absent.' if string.empty?
 
-          return if context.item_scope
+          return if context.item_env
 
-          raise MissingOption, 'The post-processor context is missing `item_scope`.', [], cause: nil
+          raise MissingOption, 'The post-processor context is missing `item_env`.', [], cause: nil
         end
 
         ##
         # @param value [String]
-        # @param context [Selectors::Context]
+        # @param context [Selectors::StepEnv]
         def initialize(value, context)
           super
 
-          @options = context[:options] || {}
-          @string = @options[:string].to_s
+          @string = context.step_config[:string].to_s
           @getter = ->(key) { item_value(key) }
         end
 
         ##
         # @return [String]
-        def get
+        def call
           Html2rss::Config::DynamicParams.call(@string, {}, getter: @getter, replace_missing_with: '')
         end
 
@@ -93,7 +97,7 @@ module Html2rss
           key = key.to_sym
           return value if key == :self
 
-          @context.item_scope.select(key)
+          @context.item_env.select(key)
         end
       end
     end

data/lib/html2rss/selectors/post_processors.rb

@@ -3,7 +3,7 @@
 module Html2rss
   class Selectors
     ##
-    # Provides a namespace for attribute post processors.
+    # Provides a namespace for selector post processors.
     module PostProcessors
       ##
       # Error raised when an unknown post processor name is requested.
@@ -32,15 +32,16 @@ module Html2rss
       }.freeze
 
       ##
-      # Shorthand method to instantiate the post processor and call `#get` on it
+      # Registry dispatcher: resolves the post-processor strategy for +name+,
+      # instantiates it with +(value, context)+, and executes its +#call+.
       #
       # @param name [String, Symbol] post-processor name from selector config
       # @param value [Object] extracted selector value
-      # @param context [Selectors::Context] post-processor context
+      # @param context [Selectors::StepEnv] post-processor step context carrying +step_config+
       # @return [Object] transformed selector value
-      def self.get(name, value, context)
+      def self.call(name, value, context)
         klass = NAME_TO_CLASS[name.to_sym] || raise(UnknownPostProcessorName, "Unknown name '#{name}'")
-        klass.new(value, context).get
+        klass.new(value, context).call
       end
     end
   end

data/lib/html2rss/selectors/{schema_doc.rb → schema_export.rb}

@@ -5,17 +5,9 @@ module Html2rss
     ##
     # Builds JSON Schema fragments from extractor / post-processor class constants.
     #
-    # Each registry class owns +DESCRIPTION+, +EXAMPLES+, and optional +OPTION_TYPES+;
+    # Each registry class owns +DESCRIPTION+, +EXAMPLES+, and optional +OPTIONS+;
     # this module is the export adapter only.
-    module SchemaDoc
-      # Maps Ruby option types to JSON Schema +type+ strings.
-      RUBY_TO_JSON_TYPE = {
-        String => 'string',
-        Integer => 'integer',
-        Hash => 'object',
-        Array => 'array'
-      }.freeze
-
+    module SchemaExport
       module_function
 
       ##
@@ -56,44 +48,33 @@ module Html2rss
       # @return [Hash{Symbol => Hash}]
       def post_processor_properties(name, klass)
         properties = { name: { type: 'string', const: name } }
-        option_types_for(klass).each do |field, ruby_type|
-          properties[field] = { type: json_type_for(ruby_type) }
+        OptionSpec.for(klass).each do |spec|
+          properties[spec.name] = property_schema_for(spec.type)
         end
         properties
       end
-      module_function :post_processor_properties
 
       ##
       # @param klass [Class]
       # @return [Array<String>]
       def post_processor_required(klass)
         required = ['name']
-        return required unless klass.const_defined?(:OPTION_TYPES)
-
-        required + klass::OPTION_TYPES.keys.map(&:to_s)
+        required + OptionSpec.for(klass).select(&:required).map { |spec| spec.name.to_s }
       end
-      module_function :post_processor_required
 
       ##
-      # @param klass [Class]
-      # @return [Hash{Symbol => Class}]
-      def option_types_for(klass)
-        types = {}
-        types.merge!(klass::OPTION_TYPES) if klass.const_defined?(:OPTION_TYPES)
-        types.merge!(klass::OPTIONAL_OPTION_TYPES) if klass.const_defined?(:OPTIONAL_OPTION_TYPES)
-        types
+      # @param ruby_type [Class, Array<Class>]
+      # @return [Hash{Symbol => String, Array<String>}]
+      def property_schema_for(ruby_type)
+        { type: json_type_for(ruby_type) }
       end
-      module_function :option_types_for
 
       ##
-      # @param ruby_type [Class]
-      # @return [String]
+      # @param ruby_type [Class, Array<Class>]
+      # @return [String, Array<String>]
       def json_type_for(ruby_type)
-        RUBY_TO_JSON_TYPE.fetch(ruby_type) do
-          raise ArgumentError, "unsupported OPTION_TYPES mapping for #{ruby_type}"
-        end
+        OptionSpec.json_type_for(ruby_type)
       end
-      module_function :json_type_for
     end
   end
 end

data/lib/html2rss/selectors/step_env.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Html2rss
+  class Selectors
+    StepEnv = Data.define(:step_config, :base_url, :time_zone, :item_env)
+
+    # Invocation environment passed to post-processors.
+    # When built via {ItemEnv#context_for}, +item_env+ carries the per-item
+    # extraction base_url for nested selects (e.g. Template).
+    class StepEnv
+      ##
+      # @param step_config [Hash] post-processor configuration (YAML step)
+      # @param base_url [String, Html2rss::Url, nil] page URL for relative resolution
+      # @param time_zone [String, nil] channel time zone for date parsing
+      # @param item_env [ItemEnv, nil]
+      # @option step_config [String] :name post-processor name
+      def initialize(step_config: {}.freeze, base_url: nil, time_zone: nil, item_env: nil)
+        base_url ||= item_env&.base_url
+        time_zone ||= item_env&.time_zone
+        super
+      end
+    end
+  end
+end