html2rss 0.25.0 → 0.27.0

data/lib/html2rss/capture.rb

@@ -0,0 +1,318 @@
+# frozen_string_literal: true
+
+module Html2rss
+  ##
+  # Analyzes a URL and produces a durable feed config: items selector + +enhance: true+.
+  #
+  # Fetches via {FeedPipeline} (including AutoFallback for +:auto+), extracts articles,
+  # then derives a reusable items CSS selector from SST segments (list → cluster → semantic).
+  #
+  # {include:file:lib/html2rss/capture/README.md}
+  class Capture # rubocop:disable Metrics/ClassLength -- segment strategies + CSS trim stay co-located
+    LEADING_TRIM_TAGS = %w[html body].freeze
+    private_constant :LEADING_TRIM_TAGS
+
+    # Ordered Segmenter strategies tried until the items selector quality gate passes.
+    SEGMENT_STRATEGIES = %i[list cluster semantic].freeze
+
+    # Minimum matched segment/article pairs required to emit an items selector.
+    MIN_SELECTOR_MATCHES = 2
+
+    ##
+    # Result of a capture operation (config plus quality meta).
+    CaptureResult = Data.define(
+      :config, :articles_count, :channel_title, :has_selectors, :segment_strategy,
+      :admission_drops, :selected_strategy
+    )
+
+    class << self
+      ##
+      # Analyzes a URL and builds a reusable feed config.
+      #
+      # @param url [String] source page URL
+      # @param strategy [Symbol] request strategy (+:auto+, +:faraday+, +:botasaurus+)
+      # @option options [String, nil] :items_selector optional selector hint
+      # @option options [Integer, nil] :max_redirects optional redirect limit override
+      # @option options [Integer, nil] :max_requests optional request budget override
+      # @option options [Integer, nil] :limit max articles to keep
+      # @option options [String, nil] :local_file_path optional local HTML file path
+      # @return [CaptureResult]
+      def build(url, strategy: :auto, **)
+        new(url, strategy:, **).build
+      end
+    end
+
+    ##
+    # @param url [String] source page URL
+    # @param strategy [Symbol] request strategy
+    # @param options [Hash] additional options
+    # @option options [String, nil] :items_selector optional selector hint
+    # @option options [Integer, nil] :max_redirects optional redirect limit override
+    # @option options [Integer, nil] :max_requests optional request budget override
+    # @option options [Integer, nil] :limit max articles to keep
+    # @option options [String, nil] :local_file_path optional local HTML file path
+    def initialize(url, strategy: :auto, **options)
+      @url = url
+      @strategy = strategy
+      @items_selector_hint = options.delete(:items_selector)
+      @max_redirects = options.delete(:max_redirects)
+      @max_requests = options.delete(:max_requests)
+      @limit = options.delete(:limit)
+      @local_file_path = options.delete(:local_file_path)
+    end
+
+    ##
+    # Runs the capture pipeline.
+    #
+    # @return [CaptureResult]
+    def build # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- outcome + selector + result assembly
+      outcome = FeedPipeline.new(raw_config).to_outcome
+      selectors, segment_strategy = derive_selectors(outcome.response, outcome.articles)
+
+      config = {
+        channel: build_channel(outcome.response),
+        selectors: selectors.empty? ? nil : selectors,
+        **strategy_stamp(outcome),
+        **local_file_request_overlay
+      }.compact
+
+      CaptureResult.new(
+        config:,
+        articles_count: outcome.articles.size,
+        channel_title: channel_title_from(outcome.response),
+        has_selectors: !selectors.empty?,
+        segment_strategy:,
+        admission_drops: outcome.admission_drops,
+        selected_strategy: outcome.selected_strategy
+      )
+    end
+
+    private
+
+    def strategy_stamp(outcome)
+      concrete = outcome.selected_strategy || concrete_request_strategy
+      return {} if concrete.nil? || concrete == :auto
+
+      { strategy: concrete }
+    end
+
+    def concrete_request_strategy
+      plan = FeedPipeline::StrategyPlan.resolve(@strategy)
+      plan.is_a?(FeedPipeline::StrategyPlan::Concrete) ? plan.strategy : nil
+    end
+
+    def raw_config
+      @raw_config ||= build_raw_config
+    end
+
+    def build_raw_config
+      Config.auto_source_config(
+        url: @url,
+        items_selector: @items_selector_hint,
+        request_controls: Config::RequestControls.from_shortcut(
+          strategy: @strategy,
+          max_redirects: @max_redirects,
+          max_requests: @max_requests
+        ),
+        limit: @limit
+      ).tap { |config| apply_local_file_path!(config) }
+    end
+
+    def apply_local_file_path!(config)
+      return unless @local_file_path
+
+      config[:strategy] = :local_file
+      config[:request] ||= {}
+      config[:request][:local_file_path] = @local_file_path
+    end
+
+    def local_file_request_overlay
+      return {} unless @local_file_path
+
+      { strategy: :local_file, request: { local_file_path: @local_file_path } }
+    end
+
+    # @return [Array(Hash, Symbol, nil)] selectors hash and winning segment strategy
+    def derive_selectors(response, articles)
+      return hint_selectors if @items_selector_hint
+      return [{}, nil] if articles.empty? || !response.html_response?
+
+      sst = SST::Normalizer.call(response.body)
+      return [{}, nil] unless sst
+
+      select_enhance_selectors(sst, articles)
+    rescue ArgumentError => error
+      Log.warn("Capture selector derivation failed: #{error.message}")
+      [{}, nil]
+    end
+
+    def hint_selectors
+      [{ items: { selector: @items_selector_hint, enhance: true } }, :hint]
+    end
+
+    def select_enhance_selectors(sst, articles) # rubocop:disable Metrics/MethodLength -- strategy loop + gate
+      link_resolver = Scoring::LinkResolver.new(@url)
+
+      SEGMENT_STRATEGIES.each 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
+
+        return [{ items: { selector: items_sel, enhance: true } }, strategy]
+      end
+
+      [{}, nil]
+    end
+
+    def match_segments_to_articles(segments, articles)
+      articles_by_url = articles.each_with_object({}) do |article, hash|
+        url_str = article.url.to_s
+        hash[url_str] = article unless url_str.empty?
+      end
+
+      segments.filter_map do |segment|
+        next unless segment.primary_link
+
+        article = find_matching_article(segment, articles_by_url)
+        { segment:, article: } if article
+      end
+    end
+
+    def find_matching_article(segment, articles_by_url) # rubocop:disable Metrics/AbcSize
+      href = segment.primary_link.attrs.href.to_s
+      return articles_by_url.values.find { |a| a.title == title_from_segment(segment) } if href.empty?
+
+      resolved = Url.from_relative(href, @url)
+      articles_by_url[resolved.to_s] || articles_by_url.values.find { |a| fuzzy_url_match?(a.url, resolved) }
+    end
+
+    def fuzzy_url_match?(article_url, resolved)
+      article_url.to_s.end_with?(resolved.path.to_s)
+    rescue StandardError
+      false
+    end
+
+    def title_from_segment(segment)
+      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
+
+    def lift_heading_link_root(root, all_roots)
+      return root unless heading_or_inner_title_link?(root)
+
+      index = SST::Index.for_node(root)
+      return root unless index
+
+      walk_usable_card(root, index, all_roots)
+    end
+
+    def walk_usable_card(root, index, all_roots)
+      candidate = root
+      parent = index.parent_of(root)
+      while parent && Html::Navigator.usable_card_parent?(parent)
+        break if contains_other_root?(parent, root, all_roots)
+
+        candidate = parent
+        parent = index.parent_of(parent)
+      end
+      candidate
+    end
+
+    def heading_or_inner_title_link?(node)
+      name = node.name.to_s
+      return false if wrapping_anchor_root?(node)
+
+      Html::Navigator::HEADING_TAGS.include?(name) || name == 'a'
+    end
+
+    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) }
+    end
+
+    def contains_other_root?(parent, root, all_roots)
+      all_roots.any? do |other|
+        next if other.equal?(root)
+
+        other.equal?(parent) || sst_descendant?(other, parent)
+      end
+    end
+
+    def sst_descendant?(child, ancestor)
+      SST::Index.for_node(child)&.descendant_of?(child, ancestor)
+    end
+
+    def shared_class_items_selector(roots)
+      shared = roots.map { |root| root.attrs.class_names }.reduce { |left, right| left & right }
+      return nil if shared.nil? || shared.empty?
+
+      "#{roots.first.name}.#{shared.min}"
+    end
+
+    def css_from_trimmed_tag_path(tag_path)
+      segments = tag_path.split('/').reject(&:empty?)
+      trimmed = trim_leading_items_segments(segments)
+      trimmed.join(' > ')
+    end
+
+    def trim_leading_items_segments(segments)
+      return segments if segments.empty?
+
+      trimmed = segments.dup
+      trimmed.shift while trimmed.any? && LEADING_TRIM_TAGS.include?(trimmed.first)
+      trimmed.shift while trimmed.length > 1 && trimmed.first == 'div'
+      trimmed.empty? ? [segments.last] : trimmed
+    end
+
+    def common_path_prefix(paths) # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity
+      return '' if paths.empty?
+
+      segments = paths.map { |p| p.split('/').reject(&:empty?) }
+      prefix = segments.first
+      segments.each do |seg|
+        i = 0
+        i += 1 while i < prefix.length && i < seg.length && prefix[i] == seg[i]
+        prefix = prefix[0...i]
+      end
+      "/#{prefix.join('/')}"
+    end
+
+    def build_channel(response)
+      {
+        url: @url,
+        title: channel_title_from(response),
+        time_zone: 'UTC'
+      }.compact
+    end
+
+    def channel_title_from(response)
+      Channel.from_response(response).title
+    rescue StandardError
+      nil
+    end
+  end
+end

data/lib/html2rss/cli.rb

@@ -9,10 +9,6 @@ module Html2rss
   # The Html2rss command line interface.
   class CLI < Thor # rubocop:disable Metrics/ClassLength
     check_unknown_options!
-    # Ordered fallback chain attempted by the feed-level :auto plan.
-    #
-    # @return [Array<Symbol>]
-    AUTO_FALLBACK_CHAIN = Html2rss::FeedPipeline::AutoFallback::CHAIN.freeze
     # Supported CLI strategy plan option values (:auto plus concrete strategies).
     #
     # @return [Array<String>]
@@ -23,7 +19,7 @@ module Html2rss
     # @return [String]
     STRATEGY_OPTION_DESC = [
       'Optional request strategy (defaults to auto; auto tries',
-      "#{AUTO_FALLBACK_CHAIN.join(' -> ')})"
+      "#{Html2rss::FeedPipeline::AutoFallback::CHAIN.join(' -> ')})"
     ].join(' ').freeze
 
     # @return [Boolean] whether Thor should terminate process on command failures
@@ -85,17 +81,61 @@ module Html2rss
     method_option :input,
                   type: :string,
                   desc: 'Local HTML file path to read input from'
+    method_option :explain,
+                  type: :boolean,
+                  desc: 'Print Status JSON to stderr (stdout stays the feed)',
+                  default: false
     # @param url [String, nil] source page URL for auto discovery
     # @return [void]
     def auto(url = nil)
       format = options.fetch(:format, 'rss')
       strategy, local_file_path, url = prepare_auto_inputs(url, options[:input])
+      feed_result = execute_feed { auto_feed_result_for(url, strategy, local_file_path) }
 
-      result = execute_feed do
-        source_call(url, strategy, local_file_path, format == 'jsonfeed')
-      end
+      explain_status!(feed_result.status) if options[:explain]
+      puts(format == 'jsonfeed' ? JSON.pretty_generate(feed_result.to_json_feed) : feed_result.to_rss)
+    end
 
-      puts(format == 'jsonfeed' ? JSON.pretty_generate(result) : result)
+    desc 'capture URL', 'Analyze a URL and print a reusable YAML feed config'
+    method_option :strategy,
+                  type: :string,
+                  desc: STRATEGY_OPTION_DESC,
+                  enum: STRATEGY_OPTION_ENUM
+    method_option :items_selector, type: :string, desc: 'CSS selector hint for items (optional)'
+    method_option :max_redirects,
+                  type: :numeric,
+                  desc: 'Maximum redirects to follow per request'
+    method_option :max_requests,
+                  type: :numeric,
+                  desc: 'Maximum requests to allow for this feed build'
+    method_option :limit,
+                  type: :numeric,
+                  desc: 'Maximum number of articles to keep (default: 25)'
+    method_option :input,
+                  type: :string,
+                  desc: 'Local HTML file path to read input from'
+    method_option :explain,
+                  type: :boolean,
+                  desc: 'Print capture quality JSON to stderr (stdout stays YAML)',
+                  default: false
+    ##
+    # Captures a URL and prints a reusable YAML config.
+    #
+    # @param url [String, nil] source page URL for capture
+    # @return [void]
+    def capture(url = nil) # rubocop:disable Metrics/AbcSize, Metrics/MethodLength -- CLI option wiring
+      strategy, local_file_path, url = prepare_auto_inputs(url, options[:input])
+      result = Html2rss::Capture.build(
+        url,
+        strategy:,
+        items_selector: options[:items_selector],
+        limit: options[:limit]&.to_i,
+        max_redirects: options[:max_redirects],
+        max_requests: options[:max_requests],
+        local_file_path:
+      )
+      explain_capture!(result) if options[:explain]
+      puts Config.to_yaml(result.config)
     end
 
     desc 'schema', 'Print the exported config JSON Schema'
@@ -123,6 +163,27 @@ module Html2rss
       puts schema_json
     end
 
+    desc 'mcp', 'Start the MCP server for AI client consumption'
+    method_option :transport,
+                  type: :string,
+                  desc: 'MCP transport protocol',
+                  enum: %w[stdio http],
+                  default: 'stdio'
+    method_option :port,
+                  type: :numeric,
+                  desc: 'Port for HTTP transport (binds 127.0.0.1)',
+                  default: 8080
+    ##
+    # Starts the MCP server for AI client consumption.
+    #
+    # @return [void]
+    def mcp
+      Html2rss::MCP.start(
+        transport: options[:transport].to_sym,
+        port: options[:port]
+      )
+    end
+
     desc 'validate YAML_FILE [feed_name]', 'Validate a YAML config with the runtime validator'
     method_option :params,
                   type: :hash,
@@ -183,7 +244,7 @@ module Html2rss
 
       file_path = check_file_exists!(input_option)
       detected_url = url || detect_base_url!(
-        file_path, 'Please specify a URL: html2rss auto [URL] --input <file>'
+        file_path, 'Please specify a URL: html2rss <command> [URL] --input <file>'
       )
 
       [:local_file, file_path, detected_url]
@@ -221,23 +282,22 @@ module Html2rss
       yield
     rescue Faraday::FollowRedirects::RedirectLimitReached => error
       raise Thor::Error,
-            "#{error.message}. retry with --max-redirects #{suggested_max_redirects} or use the final URL directly."
+            "#{error.message}. already retried the last redirect hop once; " \
+            "retry with --max-redirects #{suggested_max_redirects} or use the final URL directly."
     rescue Html2rss::RequestService::RequestBudgetExceeded => error
       raise Thor::Error,
             "#{error.message}. retry with --max-requests #{suggested_max_requests} " \
             'or increase request.max_requests in the config.'
-    rescue Html2rss::RequestService::BrowserlessConfigurationError,
-           Html2rss::RequestService::BrowserlessConnectionFailed,
-           Html2rss::RequestService::BotasaurusConfigurationError,
+    rescue Html2rss::RequestService::BotasaurusConfigurationError,
            Html2rss::RequestService::BotasaurusConnectionFailed,
+           Html2rss::RequestService::BotasaurusServiceError,
            Html2rss::RequestService::BlockedSurfaceDetected,
            Html2rss::NoFeedItemsExtracted => error
       raise Thor::Error, error.message
     end
 
-    def source_call(url, strategy, local_file_path, is_json)
-      method = is_json ? Html2rss.method(:auto_json_feed) : Html2rss.method(:auto_source)
-      method.call(
+    def auto_feed_result_for(url, strategy, local_file_path)
+      Html2rss.auto_feed_result(
         url,
         strategy:,
         items_selector: options[:items_selector],
@@ -248,6 +308,23 @@ module Html2rss
       )
     end
 
+    def explain_status!(status)
+      $stderr.puts JSON.pretty_generate(status.to_h) # rubocop:disable Style/StderrPuts -- CLI explain contract
+    end
+
+    def explain_capture!(result)
+      $stderr.puts JSON.pretty_generate( # rubocop:disable Style/StderrPuts -- CLI explain contract
+        {
+          articles_count: result.articles_count,
+          channel_title: result.channel_title,
+          has_selectors: result.has_selectors,
+          segment_strategy: result.segment_strategy,
+          selected_strategy: result.selected_strategy,
+          admission_drops: result.admission_drops
+        }.compact
+      )
+    end
+
     def check_file_exists!(path)
       File.expand_path(path).tap do |file_path|
         raise Thor::Error, "Input file does not exist: #{path}" unless File.exist?(file_path)

data/lib/html2rss/config/auto_source_contract.rb

@@ -29,6 +29,9 @@ module Html2rss
         optional(:json_state).hash do
           optional(:enabled).filled(:bool)
         end
+        optional(:xhr_articles).hash do
+          optional(:enabled).filled(:bool)
+        end
         optional(:meta_oembed).hash do
           optional(:enabled).filled(:bool)
         end
@@ -46,7 +49,6 @@ module Html2rss
 
       optional(:cleanup).hash do
         optional(:keep_different_domain).filled(:bool)
-        optional(:min_words_title).filled(:integer, gt?: 0)
       end
     end
   end

data/lib/html2rss/config/schema.rb

@@ -48,6 +48,7 @@ module Html2rss
       ##
       # Orchestrates schema assembly from runtime validator contracts plus
       # client-facing overlays.
+      # rubocop:disable Metrics/ClassLength -- overlay assembly stays in one builder
       class Builder
         class << self
           # @return [Hash{String => Object}] fully assembled JSON schema hash
@@ -60,9 +61,10 @@ module Html2rss
         def call
           schema = validator_schema
           apply_top_level(schema)
+          schema[:$defs] = registry_catalog_defs
           schema.fetch(:properties).merge!(overlay)
           schema.fetch(:properties).delete(:dynamic_params_error)
-          DeepStringifier.call(schema)
+          HashUtil.deep_stringify_keys(schema)
         end
 
         private
@@ -77,6 +79,35 @@ module Html2rss
             { 'required' => ['selectors'] },
             { 'required' => ['auto_source'] }
           ]
+
+          topics = schema.dig(:properties, :directory, :properties, :topics)
+          topics[:minItems] = 1 if topics.is_a?(Hash)
+          apply_botasaurus_schema!(schema)
+        end
+
+        def apply_botasaurus_schema!(schema)
+          request = schema.dig(:properties, :request, :properties)
+          return unless request.is_a?(Hash)
+
+          exported = Html2rss::Config::Validator::BotasaurusRequestExport
+                     .new.schema.json_schema(loose: true).except(:$schema)
+          exported[:additionalProperties] = false
+          exported.fetch(:properties).fetch(:window_size)[:additionalProperties] = false
+          request[:botasaurus] = exported
+        end
+
+        # @return [Hash{Symbol => Hash}] catalog under $defs.post_processors / $defs.extractors
+        def registry_catalog_defs
+          {
+            post_processors: catalog_from_registry(Selectors::PostProcessors::NAME_TO_CLASS),
+            extractors: catalog_from_registry(Selectors::Extractors::NAME_TO_CLASS)
+          }
+        end
+
+        # @param registry [Hash{Symbol => Class}]
+        # @return [Hash{String => Hash}]
+        def catalog_from_registry(registry)
+          registry.keys.sort.to_h { |name| [name.to_s, registry.fetch(name).schema_doc] }
         end
 
         # rubocop:disable Metrics/MethodLength, Metrics/AbcSize, Layout/LineLength
@@ -105,6 +136,13 @@ module Html2rss
             ]
           }
 
+          selector_schema = Schema.apply_selector_registry_refs!(
+            Html2rss::Config::SelectorsValidator::Selector.new.schema.json_schema(loose: true)
+          )
+          enclosure_schema = Schema.apply_selector_registry_refs!(
+            Html2rss::Config::SelectorsValidator::Enclosure.new.schema.json_schema(loose: true)
+          )
+
           {
             strategy: {
               type: 'string',
@@ -121,7 +159,7 @@ module Html2rss
               items: Html2rss::Config::Validator::StylesheetConfig.json_schema(loose: true)
             },
             auto_source: Html2rss::Config::AutoSourceContract.json_schema(loose: true).merge(
-              default: DeepStringifier.call(Html2rss::AutoSource::DEFAULT_CONFIG)
+              default: HashUtil.deep_stringify_keys(Html2rss::AutoSource::DEFAULT_CONFIG)
             ),
             selectors: {
               type: 'object',
@@ -130,14 +168,14 @@ module Html2rss
                 items: items_schema.merge(
                   description: 'Defines the items selector and optional enhancement settings.'
                 ),
-                enclosure: Html2rss::Config::SelectorsValidator::Enclosure.new.schema.json_schema(loose: true).merge(
+                enclosure: enclosure_schema.merge(
                   description: 'Describes enclosure extraction settings.'
                 ),
                 guid: reference_array('List of selector keys used to build the GUID. Each entry must reference a sibling selector key; runtime validation enforces those references.'),
                 categories: reference_array('List of selector keys whose values will be used as categories. Each entry must reference a sibling selector key; runtime validation enforces those references.')
               },
               patternProperties: {
-                '^(?!items$|enclosure$|guid$|categories$).+$' => Html2rss::Config::SelectorsValidator::Selector.new.schema.json_schema(loose: true).merge(
+                '^(?!items$|enclosure$|guid$|categories$).+$' => selector_schema.merge(
                   description: 'Dynamic selector definition keyed by attribute name.'
                 )
               },
@@ -159,31 +197,46 @@ module Html2rss
           }
         end
       end
+      # rubocop:enable Metrics/ClassLength
 
       ##
-      # Converts nested hash keys to strings so the resulting schema serializes cleanly.
-      module DeepStringifier
-        module_function
-
-        # @param object [Hash, Array, Object] nested data to normalize
-        # @return [Hash, Array, Object] deep copy with stringified hash keys
-        def call(object)
-          case object
-          when Hash
-            stringify_hash(object)
-          when Array
-            object.map { |value| call(value) }
-          when Symbol
-            object.to_s
-          else
-            object
-          end
-        end
+      # Wires extractor / post_process to thin oneOf $refs into the registry catalog.
+      #
+      # @param schema [Hash] dry-schema JSON schema fragment for a selector
+      # @return [Hash] same schema with registry $ref wiring applied
+      def apply_selector_registry_refs!(schema)
+        properties = schema.fetch(:properties)
+        properties[:extractor] = extractor_wire_schema
+        properties[:post_process] = post_process_wire_schema
+        schema
+      end
+
+      # @return [Hash{Symbol => Object}]
+      def extractor_wire_schema
+        {
+          description: 'Extractor used to pull a value from the selected element.',
+          oneOf: registry_ref_list('extractors', Selectors::Extractors::NAME_TO_CLASS)
+        }
+      end
 
-        # @param object [Hash{Object => Object}] hash whose keys should become strings
-        # @return [Hash{String => Object}] hash with recursively normalized values
-        def stringify_hash(object)
-          object.to_h { |key, value| [key.to_s, call(value)] }
+      # @return [Hash{Symbol => Object}]
+      def post_process_wire_schema
+        {
+          type: 'array',
+          description: 'Ordered transforms applied to the extracted value.',
+          items: {
+            oneOf: registry_ref_list('post_processors', Selectors::PostProcessors::NAME_TO_CLASS)
+          }
+        }
+      end
+
+      ##
+      # @param catalog [String] $defs catalog name (`extractors` or `post_processors`)
+      # @param registry [Hash{Symbol => Class}]
+      # @return [Array<Hash>] oneOf entries of `{ '$ref' => ... }`
+      def registry_ref_list(catalog, registry)
+        registry.keys.sort.map do |name|
+          { '$ref' => "#/$defs/#{catalog}/#{name}" }
         end
       end
     end