html2rss 0.27.2 → 0.28.0

data/lib/html2rss/page_recon.rb

@@ -0,0 +1,243 @@
+# frozen_string_literal: true
+
+module Html2rss
+  ##
+  # Shared page recon for MCP Inspect and FeedResolution probes.
+  #
+  # Owns surface class, native feed hints, segment stats, and a cheap AutoSource
+  # article count — not request strategy selection or MCP next-step policy.
+  class PageRecon # rubocop:disable Metrics/ClassLength -- recon bag stays co-located
+    ##
+    # Cheap surface + admission facts shared by AutoFallback gates and FeedResolution probes.
+    Assessment = Data.define(:surface_category, :articles_count, :admission_drops, :html_response) do
+      ##
+      # @return [Html2rss::SurfaceCategory]
+      def category = SurfaceCategory.coerce(surface_category)
+
+      ##
+      # @return [Boolean]
+      def weak? = category.weak?
+
+      ##
+      # @return [Boolean]
+      def blocked? = category.blocked?
+
+      ##
+      # @return [Boolean]
+      def listing_bonus? = category.listing_bonus?
+    end
+    ##
+    # Recon facts used by Inspect and FeedResolution.
+    Result = Data.define(
+      :requested_url,
+      :final_url,
+      :status,
+      :scheme_downgrade,
+      :alternate_feeds,
+      :surface_category,
+      :articles_count,
+      :admission_drops,
+      :segment_stats,
+      :html_response,
+      :content_type,
+      :blocked_surface,
+      :sst
+    ) do
+      ##
+      # @return [Hash{Symbol => Object}]
+      def to_h # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- omit-empty optional keys
+        {
+          requested_url:,
+          final_url:,
+          status:,
+          scheme_downgrade:,
+          alternate_feeds:,
+          surface_category:,
+          articles_count:,
+          html_response:,
+          content_type:,
+          **(admission_drops.any? ? { admission_drops: } : {}),
+          **(segment_stats ? { segment_stats: } : {}),
+          **(blocked_surface ? { blocked_surface: } : {}),
+          **(sst ? { sst: } : {})
+        }
+      end
+    end
+
+    ##
+    # @param response [Html2rss::RequestService::Response]
+    # @param url [String, Html2rss::Url] requested entry URL
+    # @param strategy [Symbol, nil] unused (reserved for callers that already chose a strategy)
+    # @return [Result]
+    def self.call(response:, url:, strategy: nil) # rubocop:disable Lint/UnusedMethodArgument
+      new(response:, url:).call
+    end
+
+    ##
+    # Cheap page assessment for policy gates and probe scoring (fixed AutoSource limit).
+    #
+    # @param response [Html2rss::RequestService::Response]
+    # @param url [String, Html2rss::Url]
+    # @return [Assessment]
+    def self.assess(response:, url:)
+      new(response:, url:).assess
+    end
+
+    ##
+    # Surface class only — no AutoSource extract (for empty-extract error labels).
+    #
+    # @param response [Html2rss::RequestService::Response]
+    # @param url [String, Html2rss::Url]
+    # @return [Symbol]
+    def self.surface_category_for(response:, url:)
+      new(response:, url:).surface_category_for
+    end
+
+    ##
+    # @param sst [Html2rss::SST::Document]
+    # @param url [String, Html2rss::Url]
+    # @return [Array]
+    def self.discover_segments(sst, url)
+      link_resolver = Scoring::LinkResolver.new(url)
+      AutoSource::Segmenter.call(sst, base_url: url, strategy: :list, link_resolver:)
+    rescue StandardError
+      []
+    end
+
+    ##
+    # @param response [Html2rss::RequestService::Response]
+    # @param url [String, Html2rss::Url]
+    def initialize(response:, url:)
+      @response = response
+      @url = url
+    end
+
+    ##
+    # @return [Assessment]
+    def assess
+      return feed_assessment if response.feed_response?
+
+      parsed = html_parsed_body
+      articles_count, admission_drops = cheap_articles
+      Assessment.new(
+        surface_category: surface_category(parsed),
+        articles_count:,
+        admission_drops:,
+        html_response: true
+      )
+    end
+
+    ##
+    # @return [Symbol]
+    def surface_category_for
+      return :unsupported_surface if response.feed_response?
+
+      surface_category(html_parsed_body)
+    end
+
+    ##
+    # @return [Result]
+    def call # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- assemble recon Result
+      requested = Url.from_absolute(url)
+      final = response.url
+      parsed = html_parsed_body
+      assessment = assess
+      sst_payload, segment_stats = sst_payload_and_segments(requested)
+
+      Result.new(
+        requested_url: requested.to_s,
+        final_url: final.to_s,
+        status: response.status,
+        scheme_downgrade: scheme_downgrade?(requested, final),
+        alternate_feeds: alternate_feeds_from(parsed),
+        surface_category: assessment.surface_category,
+        articles_count: assessment.articles_count,
+        admission_drops: assessment.admission_drops,
+        segment_stats:,
+        html_response: response.html_response?,
+        content_type: response.content_type,
+        blocked_surface: blocked_surface_key,
+        sst: sst_payload
+      )
+    end
+
+    private
+
+    attr_reader :response, :url
+
+    def feed_assessment
+      Assessment.new(
+        surface_category: :unsupported_surface,
+        articles_count: 0,
+        admission_drops: {},
+        html_response: false
+      )
+    end
+
+    def html_parsed_body
+      return unless response.html_response?
+
+      response.parsed_body
+    rescue RequestService::UnsupportedResponseContentType
+      nil
+    end
+
+    def surface_category(parsed)
+      return :unsupported_surface unless parsed
+
+      AutoSource::Scraper.classify_no_scraper_surface(parsed, body: response.body)
+    end
+
+    def cheap_articles
+      return [0, {}] unless response.html_response?
+
+      source = AutoSource.new(response, AutoSource::DEFAULT_CONFIG.merge(limit: 10))
+      [source.articles.size, source.admission_drops]
+    end
+
+    def sst_payload_and_segments(requested)
+      return [nil, nil] unless response.html_response?
+
+      sst = sst_document
+      return [nil, nil] unless sst
+
+      stats = segment_stats(sst, requested)
+      [
+        { node_count: sst.node_count, degraded: sst.degraded, segment_stats: stats },
+        stats
+      ]
+    end
+
+    def sst_document
+      Html2rss::SST::Normalizer.call(response.body)
+    rescue ArgumentError
+      nil
+    end
+
+    def segment_stats(sst, page_url)
+      segments = self.class.discover_segments(sst, page_url)
+      return { found: 0 } if segments.empty?
+
+      {
+        found: segments.size,
+        strategies: segments.map(&:strategy).uniq,
+        sample_paths: segments.first(5).map { |s| s.root_node.tag_path }
+      }
+    end
+
+    def scheme_downgrade?(requested, final)
+      requested.scheme == 'https' && final.scheme == 'http'
+    end
+
+    def alternate_feeds_from(parsed)
+      return [] unless parsed.is_a?(Nokogiri::HTML::Document)
+
+      Html::FeedLink.from_document(parsed).map { |link| { href: link.href, mime_type: link.mime_type } }
+    end
+
+    def blocked_surface_key
+      blocked = RequestService::BlockedSurface.interstitial_signature_for(response.body)
+      blocked[:key].to_s if blocked
+    end
+  end
+end

data/lib/html2rss/request_service/botasaurus_contract.rb

@@ -43,7 +43,7 @@ module Html2rss
       MAX_RETRIES = 3
 
       # Allowlisted ScrapeDiagnostics keys nested under diagnostics.
-      DIAGNOSTICS_KEYS = %w[request_id attempts strategy_used render_ms execution_tier challenge].freeze
+      DIAGNOSTICS_KEYS = %w[request_id attempts strategy_used render_ms execution_tier challenge timeout_phase].freeze
       # Allowlisted ChallengeSignal keys nested under diagnostics.challenge.
       CHALLENGE_KEYS = %w[blocked detected marker].freeze
 
@@ -185,10 +185,17 @@ module Html2rss
             'Botasaurus challenge block detected.'
         end
 
+        # @return [String, nil] scrape-api timeout stage when present on diagnostics
+        def timeout_phase
+          value = diagnostics['timeout_phase']
+          value.is_a?(String) && !value.empty? ? value : nil
+        end
+
         # @return [String] actionable upstream failure summary
         def failure_message
           details = ["status=#{transport_status}", "error_category=#{error_category}", "error=#{error}"]
           details << "request_id=#{request_id}" if request_id
+          details << "timeout_phase=#{timeout_phase}" if timeout_phase
           "Botasaurus scrape failed (#{details.join(', ')})."
         end
 

data/lib/html2rss/request_service/botasaurus_strategy.rb

@@ -59,7 +59,7 @@ module Html2rss
         return unless error.timeout?
 
         log_timeout!(reason: 'botasaurus_upstream')
-        raise RequestTimedOut, error.failure_message
+        raise RequestTimedOut.new(error.failure_message, timeout_phase: error.timeout_phase)
       end
 
       def response_url(final_url)

data/lib/html2rss/request_service/response.rb

@@ -14,11 +14,15 @@ module Html2rss
 
       # Bodies that look like HTML even when Content-Type is missing, empty, or wrong.
       HTML_BODY_SNIFF = /\A\s*(?:<!DOCTYPE\s+html|<html)/i
+      # Content-Type markers for RSS/Atom syndication responses.
+      FEED_CT_MARKERS = %w[rss+xml atom+xml rss atom].freeze
+      # Body sniff for unlabeled syndication (first 800 bytes, downcased).
+      FEED_BODY_MARKERS = ['<rss', '<feed xmlns', '<feed '].freeze
       # Charset from Content-Type or a leading <meta charset>.
       CHARSET_PARAMETER = /charset\s*=\s*["']?([\w.:-]+)/i
       # Bytes scanned for a meta charset hint (HTML spec looks at the first 1024).
       META_CHARSET_BYTES = 2048
-      private_constant :CHARSET_PARAMETER, :META_CHARSET_BYTES
+      private_constant :CHARSET_PARAMETER, :META_CHARSET_BYTES, :FEED_CT_MARKERS, :FEED_BODY_MARKERS
 
       ##
       # @param body [String] the body of the response
@@ -74,7 +78,14 @@ module Html2rss
 
       # @return [Boolean] whether response content is HTML (header or sniffed body, never JSON)
       def html_response?
-        content_type.include?('text/html') || (!json_response? && html_looking_body?)
+        content_type.include?('text/html') || (!json_response? && !feed_response? && html_looking_body?)
+      end
+
+      # @return [Boolean] whether response content is RSS/Atom (header or sniffed body)
+      def feed_response?
+        return @feed_response if defined?(@feed_response)
+
+        @feed_response = feed_content_type? || (!json_response? && !html_looking_body? && feed_looking_body?)
       end
 
       ##
@@ -143,6 +154,19 @@ module Html2rss
       def html_looking_body?
         body.to_s.b.match?(HTML_BODY_SNIFF)
       end
+
+      def feed_content_type?
+        ct = content_type.downcase
+        return false if ct.empty? || ct.include?('html') || ct.include?('json')
+
+        # Substring match against Content-Type (not Array#intersect? on a String).
+        FEED_CT_MARKERS.any? { |marker| ct.include?(marker) } # rubocop:disable Style/ArrayIntersect
+      end
+
+      def feed_looking_body?
+        snippet = body.to_s[0, 800].downcase
+        FEED_BODY_MARKERS.any? { |marker| snippet.include?(marker) } # rubocop:disable Style/ArrayIntersect
+      end
     end
   end
 end

data/lib/html2rss/request_service.rb

@@ -31,8 +31,20 @@ module Html2rss
     class ResponseTooLarge < Html2rss::Error; end
     # Raised when blocked content surfaces are detected.
     class BlockedSurfaceDetected < Html2rss::Error; end
+
     # Raised when a request times out.
-    class RequestTimedOut < Html2rss::Error; end
+    class RequestTimedOut < Html2rss::Error
+      ##
+      # @param message [String, nil] timeout failure summary
+      # @param timeout_phase [String, nil] scrape-api stage when known (+queue+/+boot+/+work+)
+      def initialize(message = nil, timeout_phase: nil)
+        @timeout_phase = timeout_phase
+        super(message)
+      end
+
+      # @return [String, nil] scrape-api timeout stage, or nil for transport/budget timeouts
+      attr_reader :timeout_phase
+    end
 
     # Raised when Botasaurus configuration is missing or invalid.
     class BotasaurusConfigurationError < Html2rss::Error

data/lib/html2rss/request_session.rb

@@ -15,14 +15,17 @@ module Html2rss
       # @param strategy [Symbol] request strategy for the session
       # @param budget [RequestService::Budget] shared request budget
       # @param policy [RequestService::Policy] request policy (from FeedPipeline::RuntimePolicy.resources_for)
+      # @param scrape_url [String, nil] effective fetch URL when it differs from config channel URL
       # @param logger [Logger] logger used for operational warnings
       # @return [RequestSession] configured request session
-      def build(config:, strategy:, budget:, policy:, logger: Html2rss::Log)
+      # rubocop:disable Metrics/ParameterLists -- scrape_url override stays beside config
+      def build(config:, strategy:, budget:, policy:, scrape_url: nil, logger: Html2rss::Log)
         context = RequestService::Context.new(
-          url: config.url, headers: config.headers, request: config.request, policy:, budget:
+          url: scrape_url || config.url, headers: config.headers, request: config.request, policy:, budget:
         )
         new(context:, strategy:, logger:)
       end
+      # rubocop:enable Metrics/ParameterLists
     end
 
     ##

data/lib/html2rss/scrape_target.rb

@@ -0,0 +1,24 @@
+# frozen_string_literal: true
+
+module Html2rss
+  ##
+  # Immutable entry vs effective scrape URLs for one pipeline run.
+  #
+  # Replaces mutating {Config#scrape_url=} after {FeedResolution} rewrites the fetch URL.
+  ScrapeTarget = Data.define(:entry_url, :effective_url) do
+    ##
+    # @param config [Html2rss::Config]
+    # @return [ScrapeTarget]
+    def self.from_config(config)
+      entry = config.url
+      new(entry_url: entry, effective_url: entry)
+    end
+
+    ##
+    # @param url [String, Html2rss::Url]
+    # @return [ScrapeTarget]
+    def with_effective(url)
+      self.class.new(entry_url:, effective_url: Url.from_absolute(url).to_s)
+    end
+  end
+end

data/lib/html2rss/status.rb

@@ -1,6 +1,6 @@
 # frozen_string_literal: true
 
-module Html2rss
+module Html2rss # rubocop:disable Metrics/ModuleLength -- Status Data.define + marshal stay co-located
   ##
   # Shared RSS +generator+ / JSON Feed +user_comment+ formatter string.
   #
@@ -9,7 +9,7 @@ module Html2rss
   # Tallies and counters are validated and frozen at construction (including Marshal load).
   Status = Data.define(
     :version, :scraper_tallies, :dedup_dropped, :selected_strategy, :attempt_count,
-    :strategy_attempts, :admission_drops
+    :strategy_attempts, :admission_drops, :entry_url, :scrape_url, :entry_resolution
   ) do
     class << self
       ##
@@ -21,10 +21,15 @@ module Html2rss
       # @param attempt_count [Integer] auto-fallback attempt count (0 when not under +:auto+)
       # @param strategy_attempts [Array<Hash>] auto-fallback attempt hashes (empty outside +:auto+)
       # @param admission_drops [Hash{String => Integer}] Cleanup reason → count (empty when unused)
+      # @param scrape_target [Html2rss::ScrapeTarget, nil] domain URL pair (mapped to wire strings)
+      # @param entry_url [String, nil] original channel URL when entry resolution ran
+      # @param scrape_url [String, nil] effective scrape URL after resolution
+      # @param entry_resolution [Html2rss::FeedResolution::Diag, Hash, nil] resolution diagnostics
       # @return [Html2rss::Status]
-      # rubocop:disable Metrics/ParameterLists -- Status kwargs stay co-located
+      # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength -- Status kwargs stay co-located
       def build(articles:, dedup_dropped: 0, selected_strategy: nil, attempt_count: 0,
-                strategy_attempts: [], admission_drops: {})
+                strategy_attempts: [], admission_drops: {}, scrape_target: nil,
+                entry_url: nil, scrape_url: nil, entry_resolution: nil)
         tallies = articles.filter_map(&:scraper).tally.transform_keys { |klass| scraper_name(klass) }
         new(
           version: Html2rss::VERSION,
@@ -33,10 +38,13 @@ module Html2rss
           selected_strategy:,
           attempt_count:,
           strategy_attempts:,
-          admission_drops:
+          admission_drops:,
+          entry_url: entry_url || scrape_target&.entry_url,
+          scrape_url: scrape_url || scrape_target&.effective_url,
+          entry_resolution:
         )
       end
-      # rubocop:enable Metrics/ParameterLists
+      # rubocop:enable Metrics/ParameterLists, Metrics/MethodLength
 
       ##
       # @param klass [Class, #to_s] scraper class
@@ -54,10 +62,13 @@ module Html2rss
     # @param attempt_count [Integer]
     # @param strategy_attempts [Array<Hash>]
     # @param admission_drops [Hash{String => Integer}]
+    # @param entry_url [String, nil]
+    # @param scrape_url [String, nil]
+    # @param entry_resolution [Hash, nil]
     # rubocop:disable Metrics/ParameterLists, Metrics/MethodLength -- Status Data.define members
     def initialize(
       version:, scraper_tallies:, dedup_dropped:, selected_strategy: nil, attempt_count: 0,
-      strategy_attempts: [], admission_drops: {}
+      strategy_attempts: [], admission_drops: {}, entry_url: nil, scrape_url: nil, entry_resolution: nil
     )
       dedup = Integer(dedup_dropped)
       attempts = Integer(attempt_count)
@@ -70,21 +81,19 @@ module Html2rss
         selected_strategy:,
         attempt_count: attempts,
         strategy_attempts: freeze_attempts(strategy_attempts),
-        admission_drops: freeze_tallies(admission_drops)
+        admission_drops: freeze_tallies(admission_drops),
+        entry_url: freeze_optional_string(entry_url),
+        scrape_url: freeze_optional_string(scrape_url),
+        entry_resolution: freeze_entry_resolution(entry_resolution)
       )
     end
     # rubocop:enable Metrics/ParameterLists, Metrics/MethodLength
 
     ##
-    # Observability hash for web (+scraper_status+). Omits empty/absent optional keys:
-    # +:scraper_tallies+ when empty, +:selected_strategy+ when +nil+, +:attempt_count+ when zero,
-    # +:strategy_attempts+ / +:admission_drops+ when empty.
-    # Data members remain available via readers even when omitted here.
+    # Observability hash for web (+scraper_status+). Omits empty/absent optional keys.
     #
-    # @return [Hash{Symbol => Object}] always +:version+ (String), +:dedup_dropped+ (Integer);
-    #   optionally +:scraper_tallies+, +:selected_strategy+, +:attempt_count+,
-    #   +:strategy_attempts+, +:admission_drops+
-    # rubocop:disable Metrics/AbcSize -- omit-empty optional keys stay explicit
+    # @return [Hash{Symbol => Object}]
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity -- omit-empty optional keys stay explicit
     def to_h
       {
         version:,
@@ -93,10 +102,13 @@ module Html2rss
         **(selected_strategy.nil? ? {} : { selected_strategy: }),
         **(attempt_count.positive? ? { attempt_count: } : {}),
         **(strategy_attempts.any? ? { strategy_attempts: } : {}),
-        **(admission_drops.any? ? { admission_drops: } : {})
+        **(admission_drops.any? ? { admission_drops: } : {}),
+        **(entry_url ? { entry_url: } : {}),
+        **(scrape_url ? { scrape_url: } : {}),
+        **(entry_resolution ? { entry_resolution: } : {})
       }
     end
-    # rubocop:enable Metrics/AbcSize
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
 
     ##
     # Formats the RSS +generator+ string and JSON Feed +user_comment+.
@@ -115,13 +127,15 @@ module Html2rss
 
     def marshal_dump
       [version, scraper_tallies, dedup_dropped, selected_strategy, attempt_count, strategy_attempts,
-       admission_drops]
+       admission_drops, entry_url, scrape_url, entry_resolution]
     end
 
-    def marshal_load((version, scraper_tallies, dedup_dropped, selected_strategy, attempt_count,
-                      strategy_attempts, admission_drops))
+    def marshal_load(payload)
+      version, scraper_tallies, dedup_dropped, selected_strategy, attempt_count,
+        strategy_attempts, admission_drops, entry_url, scrape_url, entry_resolution = payload
       initialize(version:, scraper_tallies:, dedup_dropped:, selected_strategy:, attempt_count:,
-                 strategy_attempts:, admission_drops: admission_drops || {})
+                 strategy_attempts:, admission_drops: admission_drops || {}, entry_url:, scrape_url:,
+                 entry_resolution:)
     end
 
     def freeze_tallies(tallies)
@@ -132,6 +146,19 @@ module Html2rss
       Array(attempts).map { |attempt| attempt.to_h.freeze }.freeze
     end
 
+    def freeze_optional_string(value)
+      return if value.nil?
+
+      value.to_s.dup.freeze
+    end
+
+    def freeze_entry_resolution(value)
+      return if value.nil?
+
+      hash = value.respond_to?(:to_h) ? value.to_h : value
+      hash.to_h.transform_keys(&:to_sym).freeze
+    end
+
     def validate_counters!(dedup:, attempts:, selected_strategy:)
       raise ArgumentError, 'dedup_dropped must be >= 0' if dedup.negative?
       raise ArgumentError, 'attempt_count must be >= 0' if attempts.negative?

data/lib/html2rss/surface_category.rb

@@ -0,0 +1,63 @@
+# frozen_string_literal: true
+
+module Html2rss
+  ##
+  # Closed surface class for no-scraper / page-assessment gates.
+  #
+  # Construction: {AutoSource::Scraper.classify_no_scraper_surface} and {PageRecon.assess}.
+  # Predicates own weak/blocked/listing-bonus decisions — do not re-list WEAK sets in Policy/Scorer.
+  class SurfaceCategory
+    # Surfaces that warrant listing/feed resolution (hubs / shells — not blocked).
+    WEAK = Set[:high_entropy_surface, :app_shell, :unsupported_surface].freeze
+
+    class << self
+      ##
+      # @param value [SurfaceCategory, Symbol, String, nil]
+      # @return [SurfaceCategory]
+      def coerce(value)
+        return value if value.is_a?(self)
+        return new(name: nil) if value.nil?
+
+        new(name: value.to_sym)
+      end
+    end
+
+    ##
+    # @return [Symbol, nil]
+    attr_reader :name
+
+    ##
+    # @param name [Symbol, nil]
+    def initialize(name:)
+      @name = name
+    end
+
+    ##
+    # @return [Boolean]
+    def weak? = WEAK.include?(name)
+
+    ##
+    # @return [Boolean]
+    def blocked? = name == :blocked_surface
+
+    ##
+    # @return [Boolean] non-weak, non-blocked surface eligible for listing bonus
+    def listing_bonus? = !name.nil? && !weak? && !blocked?
+
+    ##
+    # @return [Symbol, nil]
+    def to_sym = name
+
+    ##
+    # @param other [Object]
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(self.class) && name == other.name
+    end
+    alias eql? ==
+
+    ##
+    # @return [Integer]
+    def hash = [self.class, name].hash
+  end
+end

data/lib/html2rss/syndication/README.md

@@ -0,0 +1,21 @@
+# Syndication
+
+Native RSS/Atom discovery and parse for auto-source promotion and direct feed URLs.
+
+## Ownership
+
+| Concern | Owner |
+| --- | --- |
+| Head `rel=alternate` + common path probes + status-gated feedish | `Syndication::Discovery` |
+| RSS 2.0 / Atom → article hashes | `Syndication::Parser` |
+| Strict head-only link parse (no path guessing) | `Html::FeedLink` |
+| Response Content-Type / body feed sniff | `RequestService::Response#feed_response?` (sole sniff owner; Discovery only adds HTTP status gate) |
+
+## Non-goals
+
+- Entry-URL tournament / listing resolution (`FeedResolution`)
+- Page recon / surface classification (`PageRecon`)
+- Feed channel metadata for output (`Channel` / `FeedBuilder`)
+- Ranking or quality scoring of competing feeds beyond first feedish hit
+
+Discovery stops at the first same-origin feedish URL (lazy probe). Path guessing mirrors the legacy configs `probe_rss` script; that script should eventually thin-wrap this module.

data/lib/html2rss/syndication/candidate_catalog.rb

@@ -0,0 +1,26 @@
+# frozen_string_literal: true
+
+module Html2rss
+  module Syndication
+    ##
+    # Shared path lexicon for syndication discovery and entry-resolution candidates.
+    module CandidateCatalog
+      # Common feed path suffixes probed after head +rel=alternate+ hints.
+      FEED_PATHS = %w[
+        /feed
+        /feed.xml
+        /rss
+        /rss.xml
+        /atom.xml
+        /index.xml
+        /news/rss
+        /news/feed
+        /blog/feed
+        /blog/rss.xml
+      ].freeze
+
+      # HTML listing paths probed only by {FeedResolution::CandidateGenerator}.
+      LISTING_PATHS = %w[/news /blog /releases /changelog /updates].freeze
+    end
+  end
+end