html2rss 0.30.0 → 0.31.0

data/lib/html2rss/selector_candidates.rb

@@ -0,0 +1,234 @@
+# frozen_string_literal: true
+
+module Html2rss
+  ##
+  # Ranks Capture-derived selector evidence into deterministic best-first buckets.
+  #
+  # Owns collection into buckets, deduplication, ranking, and empty-bucket semantics.
+  # Does not emit the default +a[href]+ fallback — that remains Capture's YAML path only.
+  class SelectorCandidates # rubocop:disable Metrics/ClassLength -- ranking + field CSS stay co-located
+    # Empty candidate buckets (no discovered evidence).
+    EMPTY = { items: [].freeze, title: [].freeze, link: [].freeze, published: [].freeze }.freeze
+
+    # Ranking preference for items selector derivation kind (lower is better).
+    KIND_RANK = { shared_class: 0, unique_tag: 1, path: 2 }.freeze
+    private_constant :KIND_RANK
+
+    # Ranking preference for Segmenter strategy order (lower is better).
+    STRATEGY_RANK = { list: 0, cluster: 1, semantic: 2 }.freeze
+    private_constant :STRATEGY_RANK
+
+    # Minimum roots that must share a relative field selector.
+    DEFAULT_MIN_MATCHES = 2
+    private_constant :DEFAULT_MIN_MATCHES
+
+    # Class token that identifies a non-heading title node. Same pattern title_node matches.
+    TITLE_CLASS_PATTERN = /title|font-bold|font-semibold/
+    private_constant :TITLE_CLASS_PATTERN
+
+    class << self
+      ##
+      # @return [Hash{Symbol=>Array}] frozen empty buckets
+      def empty = EMPTY
+
+      ##
+      # Ranks items evidence and derives title/link/published field selectors.
+      #
+      # @param items_evidence [Array<Hash>] each with +:selector+, +:enhance+, +:strategy+,
+      #   +:kind+, +:match_count+, and +:roots+ (SST nodes under the items selector)
+      # @param min_matches [Integer] minimum repeated field evidence across roots
+      # @return [Hash{Symbol=>Array<Hash>}] +:items+, +:title+, +:link+, +:published+
+      def call(items_evidence:, min_matches: DEFAULT_MIN_MATCHES)
+        new(items_evidence:, min_matches:).call
+      end
+    end
+
+    ##
+    # @param items_evidence [Array<Hash>]
+    # @param min_matches [Integer]
+    def initialize(items_evidence:, min_matches: DEFAULT_MIN_MATCHES)
+      @items_evidence = Array(items_evidence)
+      @min_matches = min_matches
+    end
+
+    ##
+    # @return [Hash{Symbol=>Array<Hash>}]
+    def call
+      items = rank_items(@items_evidence)
+      return EMPTY if items.empty?
+
+      roots = roots_for(items.first, @items_evidence)
+      {
+        items:,
+        title: field_bucket(roots, :title),
+        link: field_bucket(roots, :link),
+        published: field_bucket(roots, :published)
+      }
+    end
+
+    private
+
+    def rank_items(evidence)
+      evidence
+        .sort_by { |entry| item_rank_key(entry) }
+        .each_with_object([]) do |entry, ranked|
+          selector = entry[:selector].to_s
+          next if selector.empty? || ranked.any? { |c| c[:selector] == selector }
+
+          ranked << item_candidate(entry)
+        end
+    end
+
+    def item_candidate(entry)
+      {
+        selector: entry[:selector].to_s,
+        enhance: entry[:enhance],
+        sample: visible_sample(Array(entry[:roots]).first)
+      }
+    end
+
+    def item_rank_key(entry)
+      [
+        KIND_RANK.fetch(entry[:kind], 99),
+        STRATEGY_RANK.fetch(entry[:strategy], 99),
+        -entry[:match_count].to_i,
+        entry[:selector].to_s
+      ]
+    end
+
+    def roots_for(top_item, evidence)
+      match = evidence.find { |entry| entry[:selector].to_s == top_item[:selector] }
+      Array(match&.fetch(:roots, nil))
+    end
+
+    def field_bucket(roots, field)
+      usable = roots.grep(SST::Node)
+      return [] if usable.size < @min_matches
+
+      rank_field_tallies(count_field_selectors(usable, field))
+    end
+
+    def count_field_selectors(roots, field)
+      roots.each_with_object({}) do |root, tallies|
+        node = field_node(root, field)
+        selector = relative_field_selector(root, field)
+        next unless selector
+
+        tallies[selector] ||= { count: 0, sample: visible_sample(node) }
+        tallies[selector][:count] += 1
+      end
+    end
+
+    def rank_field_tallies(tallies)
+      tallies
+        .select { |_selector, data| data[:count] >= @min_matches }
+        .sort_by { |selector, data| [-data[:count], selector.length, selector] }
+        .map { |selector, data| { selector:, sample: data[:sample] } }
+    end
+
+    def visible_sample(node)
+      node&.visible_text.to_s.gsub(/\s+/, ' ').strip
+    end
+
+    def relative_field_selector(root, field)
+      node = field_node(root, field)
+      token = identifying_title_class(node) if field == :title
+      relative_css(root, node, class_token: token)
+    end
+
+    def field_node(root, field)
+      case field
+      when :title then title_node(root)
+      when :link then link_node(root)
+      when :published then published_node(root)
+      end
+    end
+
+    def title_node(root)
+      headings = root.find_all(&:heading?)
+      return best_heading(headings) if headings.any?
+
+      root.find do |node|
+        next if node.equal?(root)
+
+        identifying_title_class(node) && !node.visible_text.to_s.strip.empty?
+      end
+    end
+
+    def best_heading(headings)
+      min_name = headings.map { |node| node.name.to_s }.min
+      headings.select { |node| node.name.to_s == min_name }
+              .max_by { |node| node.visible_text.to_s.size }
+    end
+
+    def link_node(root)
+      return if root.link?
+
+      root.find(&:link?)
+    end
+
+    def published_node(root)
+      root.find do |node|
+        next if node.equal?(root)
+
+        node.name == :time || !node.attrs.datetime.to_s.empty?
+      end
+    end
+
+    # First class that title_node used to accept this node, not the lexicographically smallest token.
+    def identifying_title_class(node)
+      return if node.nil? || node.heading?
+
+      node.attrs.class_names.find { |name| name.match?(TITLE_CLASS_PATTERN) }
+    end
+
+    def relative_css(root, node, class_token:)
+      return if node.nil? || node.equal?(root)
+      return "#{node.name}.#{css_escape_ident(class_token)}" if class_token
+
+      relative_path_css(root, node)
+    end
+
+    # CSSOM "serialize an identifier" (CSS.escape). Class tokens are untrusted HTML.
+    def css_escape_ident(token)
+      return '\\-' if token == '-'
+
+      token.each_char.with_index.map { |char, index| css_escaped_char(char, index, token) }.join
+    end
+
+    def css_escaped_char(char, index, token)
+      code = char.ord
+      return "\uFFFD" if code.zero?
+      return "\\#{code.to_s(16)} " if css_hex_escape?(code, index, token)
+      return char if css_ident_literal?(code)
+
+      "\\#{char}"
+    end
+
+    def css_hex_escape?(code, index, token)
+      code.between?(1, 0x1F) || code == 0x7F ||
+        (index.zero? && code.between?(0x30, 0x39)) ||
+        (index == 1 && code.between?(0x30, 0x39) && token.start_with?('-'))
+    end
+
+    def css_ident_literal?(code)
+      code >= 0x80 || code == 0x2D || code == 0x5F ||
+        code.between?(0x30, 0x39) || code.between?(0x41, 0x5A) || code.between?(0x61, 0x7A)
+    end
+
+    def relative_path_css(root, node)
+      root_parts = path_parts(root)
+      node_parts = path_parts(node)
+      return unless node_parts[0, root_parts.length] == root_parts
+
+      rel = node_parts[root_parts.length..]
+      return if rel.nil? || rel.empty?
+
+      rel.join(' > ')
+    end
+
+    def path_parts(node)
+      node.tag_path.to_s.split('/').reject(&:empty?)
+    end
+  end
+end

data/lib/html2rss/selectors/README.md

@@ -0,0 +1,64 @@
+# Selectors
+
+How html2rss extracts feed item fields from a page when a config declares CSS `selectors:`.
+
+## What and when
+
+`Html2rss::Selectors` is the **orchestrator** for the traditional selector path: match item nodes, dispatch each configured field through extractors and optional post-processors, then build `Article` hashes. Prefer this when you know the list markup. Prefer `auto_source:` when you want article guessing without hand-written selectors (see {file:lib/html2rss/auto_source/README.md}).
+
+YAML / MCP wire vocabulary is unchanged (`selectors`, `extractor`, `post_process`). Ruby type names below are the internal API.
+
+## Live flow
+
+1. **Parse** — HTML stays on `Response#parsed_body`. JSON responses are converted once via `JsonXml` into an HTML5 fragment so CSS selectors still run.
+2. **Items** — `items.selector` finds each card/node. Omitted, blank, and `Selectors::DEFAULT_ITEMS_SELECTOR` expand to `Html::Navigator::MAIN_ANCHOR_SELECTOR` (permalink anchors). Any other selector, including `a` and `.card`, is used as written. `Config.prepare_defaults` fills that default, with `enhance: true`, only when `selectors:` is present. `enhance: true` fills missing fields via `Html::ArticleExtractor` (list-card enrichment). Enhancement is skipped when title, url, description, published_at, enclosures, and categories are already populated.
+3. **Field dispatch** (private on `Selectors`) — for each selectable key (`title`, `url`, `enclosure`, `categories`, …):
+   - Regular fields → `Extractors.call` → optional `PostProcessors.call` chain
+   - Special keys → enclosure wrap, guid fan-out, multi-node categories
+4. **Article** — values land on `Html2rss::Article` (`enclosure` YAML → `enclosures` on the Article).
+
+```text
+Selectors (orchestrator)
+  └─ ItemEnv
+       └─ field dispatch (private)
+            ├─ Extractors::*#call(**config, xml:) + OPTIONS: [OptionSpec]
+            └─ PostProcessors::*#call + StepEnv(base_url:, time_zone:, step_config:, item_env:)
+```
+
+## The Three Layers of #call
+
+| Layer | Entrypoint | Role | Inputs / Outputs |
+| --- | --- | --- | --- |
+| **Registry dispatcher** | `Extractors.call(config, xml)` | Resolves strategy from `NAME_TO_CLASS`, instantiates with `**config`, executes `#call` | `(config Hash, xml Node)` → extracted value |
+| **Registry dispatcher** | `PostProcessors.call(name, value, context)` | Resolves strategy from `NAME_TO_CLASS`, passes `StepEnv`, executes `#call` | `(name, value, StepEnv)` → transformed value |
+| **Strategy execution** | `Extractors::*#call` | Polymorphic instance execution on extractor strategies | Keyword config on `initialize`, returns extracted Object |
+| **Strategy execution** | `PostProcessors::*#call` | Polymorphic instance execution on post-processor strategies | Reads `@value` and `@context`, returns transformed Object |
+| **Data converter** | `JsonXml.call(object)` | Internal helper converting JSON object to XML string fragment | `(Hash / Array)` → `String` XML fragment |
+| **Standalone sanitizer** | `SanitizeHtml.call(html, url)` | Cached helper for description/standalone sanitization | `(html, url)` → sanitized HTML String |
+
+## Extractor vs PostProcessor
+
+| Role | Registry | Verb | Config |
+| --- | --- | --- | --- |
+| Extractor | `Extractors::NAME_TO_CLASS` | `#call` / `Extractors.call` | YAML `extractor:` + strategy `OPTIONS` |
+| Post-processor | `PostProcessors::NAME_TO_CLASS` | `#call` / `PostProcessors.call` | YAML `post_process:` steps with `name:` + `OPTIONS` |
+
+`Extractors::Attribute` is the HTML-attribute strategy — not the field-dispatch layer (that is private on `Selectors`).
+
+## ItemEnv and StepEnv
+
+- **`ItemEnv`** — per-item extraction environment: node, `base_url`, scraper, `time_zone`. Nested selects reuse one env via `#select`.
+- **`StepEnv`** — post-processor invocation bag: `step_config` (Hash), `base_url`, `time_zone`, `item_env`. Built by `ItemEnv#context_for(step_config:)`. Distinct from `OptionSpec` (static strategy introspection). Channel URL on Test / MCP is a different field.
+
+## OptionSpec vs SchemaExport
+
+- **`OptionSpec`** — introspection & validation SoT (`for(klass)`, `expectation_for`, `valid_type?`, `error_message`, `json_type`) with **Ruby-typed** `type:` / `required:`. Strategies own `OPTIONS: [OptionSpec, …]`.
+- **`SchemaExport`** — JSON Schema adapter only (`for_extractor`, `for_post_processor`), consuming `OptionSpec#json_type`. `Config::IssueMapper` maps Ruby expectations → JSON via `OptionSpec.json_type_for` so ValidationIssue `expected` wire shape stays stable.
+
+## Constraints
+
+- Class / YAML name stays `Selectors`.
+- Strategy verb is `#call`.
+- `gsub` rejects a `pattern` longer than 256 characters as written, or whose star-height is greater than 1; `Html2rss.validate` and extraction share that compile.
+
+See also {file:CONTEXT CONTEXT.md} for registry ownership and {Html2rss::Config::SelectorsValidator} for Dry validation of the selectors hash.

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

@@ -24,13 +24,12 @@ module Html2rss
       # In case you're extracting a date or a time, consider parsing it
       # during post processing with {PostProcessors::ParseTime}.
       class Attribute
-        # Config-facing option types (excluding shared selector fields supplied at runtime).
-        OPTION_TYPES = { attribute: String }.freeze
-
-        # The available options for the attribute extractor.
-        Options = Struct.new('AttributeOptions', :selector, :attribute, keyword_init: true)
+        # Config-facing options contract (validator introspection; +selector+ is runtime-only).
+        OPTIONS = [
+          OptionSpec.new(name: :attribute, type: String)
+        ].freeze
 
-        # JSON Schema description exported via +schema_doc+.
+        # JSON Schema description exported via +schema_export+.
         DESCRIPTION = 'Return the value of an HTML attribute on the selected element. ' \
                       'Requires sibling selector option `attribute` (attribute name).'
 
@@ -40,26 +39,25 @@ module Html2rss
         ].freeze
 
         # @return [Hash{Symbol => Object}] JSON Schema fragment for this extractor name
-        def self.schema_doc = SchemaDoc.for_extractor(name: :attribute, klass: self)
+        def self.schema_export = SchemaExport.for_extractor(name: :attribute, klass: self)
 
         ##
         # Initializes the Attribute extractor.
         #
         # @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)
+        # @param attribute [String, nil] attribute name to extract from the selected element
+        # @param selector [String, nil] CSS selector used to find the element
+        def initialize(xml, attribute: nil, selector: nil, **)
+          @attribute = attribute
+          @element = Extractors.element(xml, selector, first: true)
         end
 
         ##
         # Retrieves and returns the attribute's value as a string.
         #
         # @return [String] The value of the attribute.
-        def get
-          @element.attr(@options.attribute).to_s
+        def call
+          @element&.[](@attribute).to_s
         end
       end
     end

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

@@ -6,7 +6,7 @@ module Html2rss
       ##
       # Returns the value of the +href+ attribute.
       # It always returns absolute URLs. If the extracted +href+ value is a
-      # relative URL, it prepends the channel's URL.
+      # relative URL, it prepends the page base URL.
       #
       # Imagine this +a+ HTML element with a +href+ attribute:
       #
@@ -24,12 +24,12 @@ module Html2rss
       # Would return:
       #    'http://blog-without-a-feed.example.com/posts/latest-findings'
       class Href
-        # The available options for the href (attribute) extractor.
-        Options = Struct.new('HrefOptions', :selector, :channel, keyword_init: true)
+        # Config-facing options contract (none).
+        OPTIONS = [].freeze
 
-        # JSON Schema description exported via +schema_doc+.
+        # JSON Schema description exported via +schema_export+.
         DESCRIPTION = 'Return the absolute URL from the selected element\'s `href` attribute ' \
-                      '(relative hrefs are resolved against the channel URL).'
+                      '(relative hrefs are resolved against the page base URL).'
 
         # Example extractor name values for JSON Schema +examples+.
         EXAMPLES = [
@@ -37,29 +37,28 @@ module Html2rss
         ].freeze
 
         # @return [Hash{Symbol => Object}] JSON Schema fragment for this extractor name
-        def self.schema_doc = SchemaDoc.for_extractor(name: :href, klass: self)
+        def self.schema_export = SchemaExport.for_extractor(name: :href, klass: self)
 
         ##
         # Initializes the Href extractor.
         #
         # @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)
-          @href = @element.attr('href').to_s
+        # @param base_url [String, Html2rss::Url, nil] page base URL for relative hrefs
+        # @param selector [String, nil] CSS selector used to find the link element
+        def initialize(xml, base_url: nil, selector: nil, **)
+          @base_url = base_url
+          @element = Extractors.element(xml, selector, first: true)
+          @href = @element&.[]('href').to_s
         end
 
         ##
         # Retrieves and returns the normalized absolute URL.
         #
-        # @return [String] The absolute URL.
-        def get
+        # @return [Html2rss::Url, nil] The absolute URL.
+        def call
           return nil unless @href
 
-          Url.from_relative(@href, @options.channel[:url])
+          Url.from_relative(@href, @base_url)
         end
       end
     end

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

@@ -23,10 +23,10 @@ module Html2rss
       # Always ensure to sanitize the HTML during post-processing with
       # {PostProcessors::SanitizeHtml}.
       class Html
-        # The available options for the html extractor.
-        Options = Struct.new('HtmlOptions', :selector, keyword_init: true)
+        # Config-facing options contract (none).
+        OPTIONS = [].freeze
 
-        # JSON Schema description exported via +schema_doc+.
+        # JSON Schema description exported via +schema_export+.
         DESCRIPTION = 'Return the outer HTML of the selected element. ' \
                       'Sanitize during post-processing (e.g. `sanitize_html`).'
 
@@ -36,23 +36,22 @@ module Html2rss
         ].freeze
 
         # @return [Hash{Symbol => Object}] JSON Schema fragment for this extractor name
-        def self.schema_doc = SchemaDoc.for_extractor(name: :html, klass: self)
+        def self.schema_export = SchemaExport.for_extractor(name: :html, klass: self)
 
         ##
         # Initializes the Html extractor.
         #
         # @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)
+        # @param selector [String, nil] CSS selector used to find the element
+        def initialize(xml, selector: nil, **)
+          @element = Extractors.element(xml, selector)
         end
 
         ##
         # Retrieves and returns the HTML content of the element.
         #
         # @return [String] The HTML content.
-        def get
+        def call
           @element.to_s
         end
       end

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

@@ -16,13 +16,12 @@ module Html2rss
       # Would return:
       #    'Foobar'
       class Static
-        # Config-facing option types (excluding shared selector fields supplied at runtime).
-        OPTION_TYPES = { static: String }.freeze
-
-        # The available option for the static extractor.
-        Options = Struct.new('StaticOptions', :static, keyword_init: true)
+        # Config-facing options contract (validator introspection).
+        OPTIONS = [
+          OptionSpec.new(name: :static, type: String)
+        ].freeze
 
-        # JSON Schema description exported via +schema_doc+.
+        # JSON Schema description exported via +schema_export+.
         DESCRIPTION = 'Return a fixed value from sibling selector option `static` (no DOM read).'
 
         # Example extractor name values for JSON Schema +examples+.
@@ -31,24 +30,23 @@ module Html2rss
         ].freeze
 
         # @return [Hash{Symbol => Object}] JSON Schema fragment for this extractor name
-        def self.schema_doc = SchemaDoc.for_extractor(name: :static, klass: self)
+        def self.schema_export = SchemaExport.for_extractor(name: :static, klass: self)
 
         ##
         # Initializes the Static extractor.
         #
         # @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
+        # @param static [String, Symbol, nil] static value returned by this extractor
+        def initialize(_xml = nil, static: nil, **)
+          @static = static
         end
 
         ##
         # Retrieves and returns the static value.
         #
-        # @return [String, Symbol] The static value provided in options.
-        def get
-          @options.static
+        # @return [String, Symbol, nil] The static value.
+        def call
+          @static
         end
       end
     end

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

@@ -21,10 +21,10 @@ module Html2rss
       # Would return:
       #    'Lorem ipsum dolor ...'
       class Text
-        # The available options for the text extractor.
-        Options = Struct.new('TextOptions', :selector, keyword_init: true)
+        # Config-facing options contract (none).
+        OPTIONS = [].freeze
 
-        # JSON Schema description exported via +schema_doc+.
+        # JSON Schema description exported via +schema_export+.
         DESCRIPTION = 'Return collapsed visible text of the selected element (default extractor).'
 
         # Example extractor name values for JSON Schema +examples+.
@@ -33,23 +33,22 @@ module Html2rss
         ].freeze
 
         # @return [Hash{Symbol => Object}] JSON Schema fragment for this extractor name
-        def self.schema_doc = SchemaDoc.for_extractor(name: :text, klass: self)
+        def self.schema_export = SchemaExport.for_extractor(name: :text, klass: self)
 
         ##
         # Initializes the Text extractor.
         #
         # @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)
+        # @param selector [String, nil] CSS selector used to find the element
+        def initialize(xml, selector: nil, **)
+          @element = Extractors.element(xml, selector)
         end
 
         ##
         # Retrieves and returns the text content of the element.
         #
         # @return [String] The text content.
-        def get
+        def call
           @element.text.to_s.strip.gsub(/\s+/, ' ')
         end
       end

data/lib/html2rss/selectors/extractors.rb

@@ -17,35 +17,48 @@ module Html2rss
         text: Text
       }.freeze
 
-      ##
-      # Maps the extractor class to its corresponding options class.
-      ITEM_OPTION_CLASSES = Hash.new do |hash, klass|
-        hash[klass] = klass.const_get(:Options)
-      end
-
       # Extractor used when none is explicitly configured.
       DEFAULT_EXTRACTOR = :text
-
       class << self
         ##
         # Retrieves an element from Nokogiri XML based on the selector.
         #
-        # @param xml [Nokogiri::XML::Document]
+        # Attribute-style extractors pass +first: true+ so Nokogiri can use +at_css+
+        # when only the first match is consumed. Text/HTML keep +css+ so every
+        # match is concatenated. Category collection also uses the default.
+        #
+        # @param xml [Nokogiri::XML::Document, Nokogiri::XML::Node]
         # @param selector [String, nil]
-        # @return [Nokogiri::XML::ElementSet] selected XML elements
-        def element(xml, selector)
-          selector ? xml.css(selector) : xml
-        end
+        # @param first [Boolean] when true, return the first match via +at_css+
+        # @return [Nokogiri::XML::Node, Nokogiri::XML::NodeSet, nil] selected XML elements
+        def element(xml, selector, first: false)
+          return xml unless selector
 
-        # @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
-        def get(attribute_options, xml)
-          extractor_class = NAME_TO_CLASS[attribute_options[:extractor]&.to_sym || DEFAULT_EXTRACTOR]
-          options = ITEM_OPTION_CLASSES[extractor_class].new(attribute_options.slice(*extractor_class::Options.members))
+          first ? xml.at_css(selector) : xml.css(selector)
+        end
 
-          extractor_class.new(xml, options).get
+        ##
+        # Registry dispatcher: resolves the extractor strategy for +config+,
+        # instantiates it with options, and executes its +#call+.
+        #
+        # +base_url+ and +selector+ can be supplied without merging a new Hash
+        # into the (static) field config on every item.
+        #
+        # @param config [Hash{Symbol => Object}]
+        #   Should contain at least `:extractor` (the name) and options for that extractor.
+        # @param xml [Nokogiri::XML::Node, Nokogiri::XML::NodeSet]
+        # @param base_url [String, Html2rss::Url, nil] page base URL for relative hrefs
+        # @param selector [String, nil] CSS selector override (pass +nil+ to use +xml+ as-is)
+        # @return [Object] extracted value from the strategy instance
+        def call(config, xml, base_url: nil, selector: config[:selector])
+          extractor_class = NAME_TO_CLASS[config[:extractor]&.to_sym || DEFAULT_EXTRACTOR]
+          extractor_class.new(
+            xml,
+            selector:,
+            attribute: config[:attribute],
+            static: config[:static],
+            base_url: base_url || config[:base_url]
+          ).call
         end
       end
     end

data/lib/html2rss/selectors/item_env.rb

@@ -0,0 +1,31 @@
+# frozen_string_literal: true
+
+module Html2rss
+  class Selectors
+    ItemEnv = Data.define(:item, :base_url, :scraper, :time_zone)
+
+    ##
+    # Per-item extraction environment: owns the article node, page +base_url+, and
+    # +time_zone+ for one extraction pass.
+    #
+    # Distinct from {StepEnv}, which is the post-processor invocation bag (+step_config+).
+    class ItemEnv
+      ##
+      # Selects an attribute using this env's item and base_url.
+      #
+      # @param name [Symbol, String]
+      # @return [Object, Array<Object>]
+      def select(name) = scraper.select_in_scope(name, self)
+
+      ##
+      # Builds a post-processor {StepEnv} carrying this env for nested selects.
+      #
+      # @param step_config [Hash] post-processor configuration from the selector config
+      # @option step_config [String] :name post-processor name
+      # @return [StepEnv]
+      def context_for(step_config:)
+        StepEnv.new(step_config:, item_env: self)
+      end
+    end
+  end
+end