html2rss 0.30.0 → 0.31.0

data/lib/html2rss/auto_source/segmenter/list.rb

@@ -4,8 +4,8 @@ module Html2rss
   class AutoSource
     class Segmenter
       ##
-      # Builds repeated-list article segments from tag_path frequency
-      # (port of Discovery::ListCandidates using tag_path instead of xpath).
+      # Builds repeated-list article segments by grouping cards under a shared parent.
+      # When the document has a +main+ or +[role=main]+, anchors outside it are dropped.
       module List
         module_function
 
@@ -30,40 +30,55 @@ module Html2rss
         end
 
         def article_pairs(segmenter)
-          by_path = relevant_links_by_path(segmenter)
-          top_paths(segmenter, by_path).flat_map do |path|
-            by_path.fetch(path, []).filter_map do |node|
-              article_tag = parent_until_boundary(segmenter, node)
-              next unless article_tag
-
-              [article_tag, node]
-            end
-          end
+          top_groups(segmenter).flatten(1)
         end
         module_function :article_pairs
         private_class_method :article_pairs
 
-        def relevant_links_by_path(segmenter)
-          by_path = Hash.new { |hash, path| hash[path] = [] }
-          segmenter.index.each_node do |node|
+        def top_groups(segmenter)
+          cards_by_parent(segmenter)
+            .select { |_parent, cards| cards.size >= segmenter.minimum_selector_frequency }
+            .max_by(segmenter.use_top_selectors) { |_parent, cards| cards.size }
+            .map(&:last)
+        end
+        module_function :top_groups
+        private_class_method :top_groups
+
+        def cards_by_parent(segmenter) # rubocop:disable Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+          index = segmenter.index
+          main = main_landmark(index)
+          groups = {}.compare_by_identity
+
+          index.each_node do |node|
             next unless node.link?
-            next if segmenter.index.ignored_chrome?(node)
+            next if index.ignored_chrome?(node)
             next unless relevant_anchor?(segmenter, node)
+            next if main && !inside_main?(index, node, main)
+
+            card = parent_until_boundary(segmenter, node)
+            next unless card
 
-            by_path[node.tag_path] << node
+            parent = index.parent_of(card)
+            next unless parent
+
+            (groups[parent] ||= []) << [card, node]
           end
-          by_path
+          groups
+        end
+        module_function :cards_by_parent
+        private_class_method :cards_by_parent
+
+        def main_landmark(index)
+          index.each_node.find { |node| node.name == :main || node.attrs.raw['role'] == 'main' }
         end
-        module_function :relevant_links_by_path
-        private_class_method :relevant_links_by_path
+        module_function :main_landmark
+        private_class_method :main_landmark
 
-        def top_paths(segmenter, by_path)
-          by_path.select { |_path, nodes| nodes.size >= segmenter.minimum_selector_frequency }
-                 .max_by(segmenter.use_top_selectors) { |_path, nodes| nodes.size }
-                 .map(&:first)
+        def inside_main?(index, node, main)
+          node.equal?(main) || index.descendant_of?(node, main)
         end
-        module_function :top_paths
-        private_class_method :top_paths
+        module_function :inside_main?
+        private_class_method :inside_main?
 
         def relevant_anchor?(segmenter, node)
           facts = segmenter.link_resolver.destination_facts(node)
@@ -77,12 +92,15 @@ module Html2rss
         module_function :relevant_anchor?
         private_class_method :relevant_anchor?
 
+        BOUNDARY_TAGS = Set[:body, :html].freeze
+        private_constant :BOUNDARY_TAGS
+
         def parent_until_boundary(segmenter, node)
           index = segmenter.index
-          link_counts = Hash.new { |hash, curr| hash[curr] = count_links(curr) }
+          link_counts = Hash.new { |hash, curr| hash[curr] = count_relevant_links(segmenter, curr) }
 
           index.parent_until(node, lambda { |curr|
-            return true if %i[body html].include?(curr.name)
+            return true if BOUNDARY_TAGS.include?(curr.name)
             return false if index.ignored_chrome?(curr)
 
             parent = index.parent_of(curr)
@@ -92,11 +110,16 @@ module Html2rss
         module_function :parent_until_boundary
         private_class_method :parent_until_boundary
 
-        def count_links(node)
-          node.link? ? 1 : node.descendants.count(&:link?)
+        def count_relevant_links(segmenter, node)
+          # Chrome inside a card must not stop the walk before the shared list parent.
+          if node.link?
+            relevant_anchor?(segmenter, node) ? 1 : 0
+          else
+            node.count_descendants { |child| child.link? && relevant_anchor?(segmenter, child) }
+          end
         end
-        module_function :count_links
-        private_class_method :count_links
+        module_function :count_relevant_links
+        private_class_method :count_relevant_links
       end
     end
   end

data/lib/html2rss/auto_source/segmenter.rb

@@ -7,7 +7,7 @@ module Html2rss
     #
     # Strategies:
     # - +:semantic+ — leaf article/section/li/tr/div containers with a primary link
-    # - +:list+ — repeated tag_path anchors walked to a shared container boundary
+    # - +:list+ — repeated cards grouped by parent (`main` is a filter when present)
     # - +:cluster+ — class / structure clustering for anchorless card grids
     class Segmenter
       # @param document [SST::Document]
@@ -68,11 +68,11 @@ module Html2rss
       # @param container [SST::Node]
       # @return [Boolean]
       def landmark_ancestor?(anchor, container)
-        cache = (@landmark_cache ||= {})
-        key = [anchor.object_id, container.object_id]
-        return cache[key] if cache.key?(key)
+        cache = (@landmark_cache ||= {}.compare_by_identity)
+        anchor_cache = (cache[anchor] ||= {}.compare_by_identity)
+        return anchor_cache[container] if anchor_cache.key?(container)
 
-        cache[key] = compute_landmark_ancestor?(anchor:, container:)
+        anchor_cache[container] = compute_landmark_ancestor?(anchor:, container:)
       end
 
       private

data/lib/html2rss/auto_source.rb

@@ -93,7 +93,7 @@ module Html2rss
         Scraper::SCRAPERS.sum do |scraper|
           if config.dig(:scraper, scraper.options_key, :enabled)
             opts = config.dig(:scraper, scraper.options_key)
-            scraper.respond_to?(:request_slots) ? scraper.request_slots(opts) : 0
+            scraper.request_slots(opts)
           else
             0
           end
@@ -180,7 +180,7 @@ module Html2rss
             captured_responses:
           )
           next unless instance
-          next unless Scraper.extractable_instance?(instance, parsed_body)
+          next unless instance.extractable?
 
           matched = true
           articles.concat(run_scraper(instance))

data/lib/html2rss/batch.rb

@@ -10,8 +10,10 @@ module Html2rss
     # Default worker threads for batch operations.
     DEFAULT_CONCURRENCY = 5
 
+    BatchResult = Data.define(:total, :successful, :results)
+
     # Value object representing the outcome of a batch operation.
-    BatchResult = Data.define(:total, :successful, :results) do
+    class BatchResult
       ##
       # @return [Hash{Symbol => Object}]
       def to_h

data/lib/html2rss/capture/README.md

@@ -27,7 +27,9 @@ File.write('my-feed.yml', result.yaml)
 rss = Html2rss.apply(result.config)
 ```
 
-`Html2rss.capture` and `Capture.build` both return a `CaptureResult` with YAML (`#yaml`, includes the schema modeline) and quality meta (`has_selectors`, `segment_strategy`, `admission_drops`, `selected_strategy`, `native_feed`).
+`Html2rss.capture` and `Capture.build` both return a `CaptureResult` with YAML (`#yaml`, includes the schema modeline) and quality meta (`has_selectors`, `segment_strategy`, `admission_drops`, `selected_strategy`, `native_feed`, `candidates`).
+
+`#candidates` is ranked discovery evidence: `{ items:, title:, link:, published: }` arrays (best-first, deduplicated). Items entries are `{ selector:, enhance:, sample: }`; field entries are `{ selector:, sample: }`. `sample` stays on `#candidates` only — emitted YAML is still `items` + `enhance`. Buckets may be empty when evidence is missing. The default `a[href]` YAML fallback is not listed as discovered evidence.
 
 **Wire vs internal:** user-facing **`Html2rss.apply`** ships RSS from a config Hash. Pipeline internals **`Html2rss.feed` / `feed_result`** stay unchanged — use `apply` in CLI/MCP/docs examples, not `feed`.
 
@@ -58,13 +60,13 @@ html2rss capture https://example.com --explain   # quality JSON on stderr; YAML
 1. **Request** — `FeedPipeline` (AutoFallback when `:auto`)
 2. **Discover** — AutoSource extracts admitted articles
 3. **Segment** — try SST Segmenter strategies `:list` → `:cluster` → `:semantic`
-4. **Gate** — emit items selector only when ≥ `MIN_SELECTOR_MATCHES` (2) articles match
-5. **Assemble** — `{ items: { selector:, enhance: true } }` plus channel
+4. **Gate** — keep a derived items selector when ≥ `MIN_SELECTOR_MATCHES` (2) articles match
+5. **Assemble** — `{ items: { selector:, enhance: } }` plus channel. HTML derivation misses fall back to `Selectors::DEFAULT_ITEMS_SELECTOR` (`segment_strategy: :default`) instead of omitting selectors.
 
 ## Constraints
 
 - Selector quality depends on page structure; treat output as a first draft.
-- When the quality gate fails, selectors are omitted (`has_selectors: false`) rather than inventing attribute selectors.
+- When HTML derivation misses (no articles, no SST document, fewer than `MIN_SELECTOR_MATCHES` pairs, or a rescued `ArgumentError`), Capture emits the default items selector with `segment_strategy: :default`. `enhance` still follows admission evidence (false when chrome drops are high). Non-HTML responses still omit selectors.
 - Botasaurus hops need `BOTASAURUS_SCRAPER_URL`.
 
 See also {Html2rss::AutoSource} for article discovery and {Html2rss::FeedPipeline} for the `:auto` request chain.

data/lib/html2rss/capture.rb

@@ -25,12 +25,15 @@ module Html2rss
     CHROME_DROP_THRESHOLD = 3
     private_constant :CHROME_DROP_THRESHOLD
 
-    ##
-    # Result of a capture operation (config plus quality meta).
     CaptureResult = Data.define(
       :config, :yaml, :articles_count, :channel_title, :has_selectors, :segment_strategy,
-      :admission_drops, :selected_strategy, :inferred_topics, :native_feed, :suggested_channel_url
-    ) do
+      :admission_drops, :selected_strategy, :inferred_topics, :native_feed, :suggested_channel_url,
+      :candidates
+    )
+
+    ##
+    # Result of a capture operation (config plus quality meta).
+    class CaptureResult
       # rubocop:disable Metrics/ParameterLists
       ##
       # @param config [Hash]
@@ -44,9 +47,10 @@ module Html2rss
       # @param inferred_topics [Array<String>]
       # @param native_feed [String, nil]
       # @param suggested_channel_url [String, nil]
+      # @param candidates [Hash{Symbol=>Array}, nil] ranked selector buckets from {SelectorCandidates}
       def initialize(config:, articles_count:, channel_title:, has_selectors:, segment_strategy:, # rubocop:disable Metrics/MethodLength
                      yaml: nil, admission_drops: {}, selected_strategy: nil, inferred_topics: [], native_feed: nil,
-                     suggested_channel_url: nil)
+                     suggested_channel_url: nil, candidates: nil)
         super(
           config:,
           yaml: yaml || "#{SCHEMA_MODELINE}\n#{Config.to_yaml(config)}",
@@ -58,7 +62,8 @@ module Html2rss
           selected_strategy:,
           inferred_topics:,
           native_feed:,
-          suggested_channel_url:
+          suggested_channel_url:,
+          candidates: candidates || SelectorCandidates.empty
         )
       end
       # rubocop:enable Metrics/ParameterLists
@@ -127,7 +132,7 @@ module Html2rss
     def build # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
       outcome = FeedPipeline.new(raw_config).to_outcome
       @admission_drops = outcome.admission_drops
-      selectors, segment_strategy = derive_selectors(outcome.response, outcome.articles)
+      selectors, segment_strategy, candidates = derive_selectors(outcome.response, outcome.articles)
       ch_title = @title || channel_title_from(outcome.response)
       topics = @topics || infer_topics("#{@url} #{ch_title}")
       native_feed = probe_native_feed(outcome.response) unless @force
@@ -151,7 +156,8 @@ module Html2rss
         selected_strategy: outcome.selected_strategy,
         inferred_topics: topics,
         native_feed:,
-        suggested_channel_url: suggested_channel_url(outcome)
+        suggested_channel_url: suggested_channel_url(outcome),
+        candidates:
       )
     end
 
@@ -254,40 +260,68 @@ module Html2rss
       { strategy: :local_file, request: { local_file_path: @local_file_path } }
     end
 
-    # @return [Array(Hash, Symbol, nil)] selectors hash and winning segment strategy
+    # @return [Array(Hash, Symbol, nil, Hash)] selectors, segment strategy, candidate buckets
     def derive_selectors(response, articles)
-      return hint_selectors if @items_selector_hint
-      return [{}, nil] if articles.empty? || !response.html_response?
+      return [*hint_selectors, SelectorCandidates.empty] if @items_selector_hint
+      return [{}, nil, SelectorCandidates.empty] unless response.html_response?
+      return [*default_selectors, SelectorCandidates.empty] if articles.empty?
 
       sst = SST::Normalizer.call(response.body)
-      return [{}, nil] unless sst
+      return [*default_selectors, SelectorCandidates.empty] unless sst
 
       select_enhance_selectors(sst, articles)
     rescue ArgumentError => error
       Log.warn("Capture selector derivation failed: #{error.message}")
-      [{}, nil]
+      [*default_selectors, SelectorCandidates.empty]
     end
 
     def hint_selectors
       [{ items: { selector: @items_selector_hint, enhance: resolve_enhance } }, :hint]
     end
 
-    def select_enhance_selectors(sst, articles) # rubocop:disable Metrics/MethodLength -- strategy loop + gate
+    def default_selectors
+      [{ items: { selector: Selectors::DEFAULT_ITEMS_SELECTOR, enhance: resolve_enhance } }, :default]
+    end
+
+    def select_enhance_selectors(sst, articles)
+      evidence = collect_items_evidence(sst, articles)
+      candidates = SelectorCandidates.call(items_evidence: evidence, min_matches: MIN_SELECTOR_MATCHES)
+      top = candidates[:items].first
+      return [*default_selectors, candidates] unless top
+
+      strategy = evidence.find { |entry| entry[:selector] == top[:selector] }&.fetch(:strategy)
+      items = { selector: top[:selector], enhance: top[:enhance] }
+      [{ items: }, strategy, candidates]
+    end
+
+    def collect_items_evidence(sst, articles)
       link_resolver = Scoring::LinkResolver.new(@url)
       enhance = resolve_enhance
 
-      SEGMENT_STRATEGIES.each do |strategy|
+      SEGMENT_STRATEGIES.flat_map do |strategy|
         segments = AutoSource::Segmenter.call(
           sst, base_url: @url, strategy:, permit_unanchored: false, link_resolver:
         )
         matched = match_segments_to_articles(segments, articles)
-        items_sel = items_selector(matched)
-        next unless items_sel && matched.size >= MIN_SELECTOR_MATCHES
+        next [] if matched.size < MIN_SELECTOR_MATCHES
+
+        items_evidence_for(matched, strategy:, enhance:)
+      end
+    end
 
-        return [{ items: { selector: items_sel, enhance: } }, strategy]
+    def items_evidence_for(matched, strategy:, enhance:)
+      roots = lift_heading_link_roots(matched.map { |pair| pair[:segment].root_node })
+      selector_variants_for(roots).map do |kind, selector|
+        { selector:, enhance:, strategy:, kind:, match_count: matched.size, roots: }
       end
+    end
 
-      [{}, nil]
+    def selector_variants_for(roots)
+      [
+        [:shared_class, shared_class_items_selector(roots)],
+        [:unique_tag, unique_tag_items_selector(roots)],
+        [:path, path_items_selector(roots)]
+      ].filter_map { |kind, selector| [kind, selector] if selector }
     end
 
     def match_segments_to_articles(segments, articles)
@@ -322,21 +356,6 @@ module Html2rss
       segment.root_node.visible_text.to_s.strip
     end
 
-    def items_selector(matched)
-      return nil if matched.empty?
-
-      roots = lift_heading_link_roots(matched.map { |m| m[:segment].root_node })
-      shared = shared_class_items_selector(roots)
-      return shared if shared
-
-      paths = roots.map(&:tag_path)
-      common = common_path_prefix(paths)
-      tag_path = common.empty? ? paths.first.to_s : common
-      return nil if tag_path.empty?
-
-      css_from_trimmed_tag_path(tag_path)
-    end
-
     def lift_heading_link_roots(roots)
       roots.map { |root| lift_heading_link_root(root, roots) }
     end
@@ -371,7 +390,6 @@ module Html2rss
 
     def wrapping_anchor_root?(node)
       return false unless node.name.to_s == 'a'
-      return false unless node.respond_to?(:find)
 
       tags = Html::Navigator::WRAPPING_ANCHOR_CHILD_TAGS
       node.find { |child| !child.equal?(node) && tags.include?(child.name.to_s) }
@@ -396,6 +414,20 @@ module Html2rss
       "#{roots.first.name}.#{shared.min}"
     end
 
+    def unique_tag_items_selector(roots)
+      names = roots.map { |root| root.name.to_s }.uniq
+      names.join(', ') if names.size > 1
+    end
+
+    def path_items_selector(roots)
+      paths = roots.map(&:tag_path)
+      common = common_path_prefix(paths)
+      tag_path = common.empty? ? paths.first.to_s : common
+      return if tag_path.empty?
+
+      css_from_trimmed_tag_path(tag_path)
+    end
+
     def css_from_trimmed_tag_path(tag_path)
       segments = tag_path.split('/').reject(&:empty?)
       trimmed = trim_leading_items_segments(segments)

data/lib/html2rss/channel.rb

@@ -2,8 +2,9 @@
 
 require 'time'
 
-# rubocop:disable Metrics/ModuleLength -- Channel value object owns extract + freeze + Marshal
 module Html2rss
+  Channel = Data.define(:title, :url, :description, :language, :ttl, :last_build_date, :image, :author)
+
   ##
   # Materialized channel metadata for feed builders and {FeedResult}.
   #
@@ -27,7 +28,7 @@ module Html2rss
   #   @return [Html2rss::Url, nil]
   # @!attribute [r] author
   #   @return [String, nil]
-  Channel = Data.define(:title, :url, :description, :language, :ttl, :last_build_date, :image, :author) do
+  class Channel # rubocop:disable Metrics/ClassLength -- Channel value object owns extract + freeze + Marshal
     class << self
       ##
       # Materializes channel attributes from an HTTP response and optional overrides.
@@ -193,5 +194,4 @@ module Html2rss
       Time.httpdate(value)
     end
   end
-  # rubocop:enable Metrics/ModuleLength
 end

data/lib/html2rss/cli/probe_view.rb

@@ -2,8 +2,6 @@
 
 module Html2rss
   class CLI
-    ##
-    # Display-only probe facts for inspect and recon text cards.
     ProbeView = Data.define(
       :requested,
       :final,
@@ -15,7 +13,11 @@ module Html2rss
       :alternate_feeds,
       :notes,
       :strategy
-    ) do
+    )
+
+    ##
+    # Display-only probe facts for inspect and recon text cards.
+    class ProbeView
       class << self
         ##
         # @param data [Hash] inspect wire payload

data/lib/html2rss/cli/render.rb

@@ -93,9 +93,11 @@ module Html2rss
             end
           end
         else
-          warn "\e[31m✗ Test failed\e[0m (#{source})"
-          warn "  Error: #{result.error_message}" if result.error_message
-          result.validation_errors&.each { |k, v| warn "  Schema error [#{k}]: #{Array(v).join(', ')}" }
+          $stderr.puts "\e[31m✗ Test failed\e[0m (#{source})" # rubocop:disable Style/StderrPuts
+          $stderr.puts "  Error: #{result.error_message}" if result.error_message # rubocop:disable Style/StderrPuts
+          result.validation_issues&.each do |issue|
+            $stderr.puts "  Schema error #{issue}" # rubocop:disable Style/StderrPuts
+          end
         end
       end
 
@@ -115,8 +117,7 @@ module Html2rss
         if view.final && view.final != view.requested
           puts "        Final:    #{view.final} (HTTP #{view.status || 'ERR'})"
         end
-        surface = view.surface.respond_to?(:to_s) ? view.surface.to_s : view.surface
-        puts "        Surface:  #{surface} (#{view.articles_count} articles)"
+        puts "        Surface:  #{view.surface} (#{view.articles_count} articles)"
       end
       private_class_method :probe_lines
     end

data/lib/html2rss/cli/validate.rb

@@ -29,11 +29,10 @@ module Html2rss
           if result.success?
             puts(target_files.size == 1 ? 'Configuration is valid' : "ok   #{file}") unless quiet
           else
-            error_details = result.errors.to_h
-            raise Thor::Error, "Invalid configuration: #{error_details}" if target_files.size == 1
+            raise Thor::Error, format_failure(result) if target_files.size == 1
 
             warn "FAIL #{file}"
-            error_details.each { |key, msg| warn "       #{key}: #{Array(msg).join(', ')}" }
+            result.issues.each { |issue| warn "       #{issue}" }
             failed << file
           end
         end
@@ -57,35 +56,37 @@ module Html2rss
         resolved.uniq
       end
 
-      def run_named_feed(file, feed_name, params:, quiet:)
-        result = Html2rss.validate(file, feed_name, params:)
-        raise Thor::Error, "Invalid configuration: #{result.errors.to_h}" unless result.success?
+      class << self
+        private
 
-        puts 'Configuration is valid' unless quiet
-      end
-      module_function :run_named_feed
-      private_class_method :run_named_feed
-
-      def validate_file(file, params:)
-        if file == '-'
-          Html2rss.validate($stdin.read, params:)
-        else
-          Html2rss.validate(file, params:)
+        def run_named_feed(file, feed_name, params:, quiet:)
+          result = Html2rss.validate(file, feed_name, params:)
+          raise Thor::Error, format_failure(result) unless result.success?
+
+          puts 'Configuration is valid' unless quiet
+        end
+
+        def validate_file(file, params:)
+          if file == '-'
+            Html2rss.validate($stdin.read, params:)
+          else
+            Html2rss.validate(file, params:)
+          end
         end
-      end
-      module_function :validate_file
-      private_class_method :validate_file
 
-      def path_like_config?(arg)
-        path = arg.to_s
-        return true if path.start_with?('-')
-        return true if path.end_with?('.yml', '.yaml')
-        return true if path.include?('/') || path.include?('*')
+        def format_failure(report)
+          "Invalid configuration: #{report}"
+        end
 
-        false
+        def path_like_config?(arg)
+          path = arg.to_s
+          return true if path.start_with?('-')
+          return true if path.end_with?('.yml', '.yaml')
+          return true if path.include?('/') || path.include?('*')
+
+          false
+        end
       end
-      module_function :path_like_config?
-      private_class_method :path_like_config?
     end
   end
 end

data/lib/html2rss/cli.rb

@@ -300,7 +300,7 @@ module Html2rss
     def filter_recon_results(results, verdict_filter)
       return results unless verdict_filter
 
-      expected = Recon::Verdict.coerce(verdict_filter.downcase)
+      expected = Recon::Verdict[verdict_filter.downcase]
       results.select { |r| r.verdict == expected }
     rescue ArgumentError => error
       raise Thor::Error, error.message

data/lib/html2rss/config/issue_mapper.rb

@@ -0,0 +1,108 @@
+# frozen_string_literal: true
+
+module Html2rss
+  class Config
+    ##
+    # Maps internal Dry::Validation messages to {ValidationIssue} (predicate → code).
+    # Not a public API — Dry stays inside Validator / this mapper.
+    module IssueMapper
+      # Dry schema predicates → closed {ValidationIssue::CODES}.
+      PREDICATE_CODES = {
+        key?: :missing_key,
+        filled?: :missing_key,
+        str?: :type_mismatch,
+        int?: :type_mismatch,
+        bool?: :type_mismatch,
+        hash?: :type_mismatch,
+        array?: :type_mismatch,
+        type?: :type_mismatch,
+        format?: :invalid_value,
+        included_in?: :unknown_value,
+        gt?: :constraint,
+        gteq?: :constraint,
+        lt?: :constraint,
+        lteq?: :constraint,
+        max_size?: :constraint,
+        min_size?: :constraint
+      }.freeze
+
+      class << self
+        ##
+        # @param dry_result [Dry::Validation::Result]
+        # @param values [Hash, nil] config under validation (for actual/expected dig)
+        # @return [Html2rss::Config::ValidationReport]
+        def from(dry_result, values: nil)
+          return ValidationReport.ok if dry_result.success?
+
+          ValidationReport.failure(dry_result.errors.map { |message| issue_for(message, values:) })
+        end
+
+        ##
+        # @param message [String]
+        # @return [Html2rss::Config::ValidationReport]
+        def parse_failure(message)
+          ValidationReport.failure(
+            [
+              ValidationIssue.new(path: %i[parse], code: :parse, message:)
+            ]
+          )
+        end
+
+        private
+
+        def issue_for(message, values:)
+          path = Array(message.path).compact
+          ValidationIssue.new(
+            path:,
+            code: code_for(message.predicate),
+            message: message.text,
+            expected: expected_for(path, values),
+            actual: actual_for(path, values, message)
+          )
+        end
+
+        def code_for(predicate)
+          return :invalid_value if predicate.nil?
+
+          PREDICATE_CODES.fetch(predicate) do
+            raise ArgumentError, "unmapped Dry validation predicate: #{predicate.inspect}"
+          end
+        end
+
+        def actual_for(path, values, message)
+          dug = dig_path(values, path)
+          return dug unless dug.nil?
+          return message.input if message.is_a?(Dry::Schema::Message) && !message.input.nil?
+
+          nil
+        end
+
+        def expected_for(path, values)
+          return if values.nil? || path.empty?
+          return unless path.last.is_a?(Symbol)
+
+          parent = dig_path(values, path[0...-1])
+          return unless parent.is_a?(Hash)
+
+          option = Selectors::OptionSpec.option_for(parent, path.last)
+          return unless option
+
+          {
+            type: option.json_type,
+            required: option.required
+          }
+        end
+
+        def dig_path(values, path)
+          return if values.nil? || path.empty?
+
+          path.reduce(values) do |cursor, segment|
+            break unless cursor.is_a?(Hash) || (cursor.is_a?(Array) && segment.is_a?(Integer))
+
+            cursor[segment]
+          end
+        end
+      end
+    end
+  end
+end